Collection of Tools & Utilities

home *** CD-ROM | disk | FTP | other *** search

/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / bbsutil / ckit210.zip / CKIT.DOC < prev next >

Wrap

Text File | 1991-12-22 | 186KB | 4,676 lines

C-KIT DOOR building Toolkit Library Version 2.10 Reference Manual Distributed By Data-Comp Information Systems P.O. Box 5895 Maryville, Tenn. 37802-5895 (615) 982-6537 (Hayes Ultra V.32, public line) (615) 982-8723 (Hayes Ultra V.32, private line) (615) 982-6512 (USR HST Dual Standard V.32, private line) (615) 970-7418 (USR HST Dual Standard V.32, private line) Copyright (c) 1989, 90, 91 Rickie W. Belitz Introduction Introduction C-KIT Library is an extensive library of C runtime routines that allow easy door program implementation using PCBoard 12.0 through 14.x, WILDCAT! systems, (all versions), GAP BBS, SPITFIRE BBS 3.0 and other systems using standard DOOR.SYS file along with RBBS-PC, QuickBBS, Remote Access and other systems using DORINFOx.DEF files. C-KIT 2.01 will also work properly with MikeBBS (MBBS) v9.9 and above. CKIT will automatically work with the above system. For systems not listed above, CKIT can deal with them in one of two ways. CKIT can utilize a file called GENERIC.SYS. This is for creating a system file for a system CKIT does not support. See section on GENERIC.SYS for more information. In addition, CKIT will also accept a pointer to a structure that contains the needed information for CKIT to operate. This could be the result of your program reading ANY BBS's system file. This structure will allow C-KIT to work on ANY BBS system, providing the door author reads the BBS file himself. Some other C-KIT Library's features include interrupt driven I/O, 16550AN UART support, FOSSIL support, provides information available from the PCBoard .sys files, database files, multi-node support (file sharing), multi-BBS support, local sysop function keys and many more utilities are included for the door author. The C-KIT Library routines are written entirely in Assembly language using SLR's Optasm. The routines make use of C library functions when possible and are compatible with Microsoft C, Microsoft QuickC, TURBO C, and TURBO C++. C-KIT Library supports the small, medium and large models. Microsoft is a registered trademark, and QuickC is a trademark of the Microsoft Corporation. TURBO C is a registered trademark of Borland International Inc. TURBO C++ is a registered trademark of Borland International Inc. PCBoard is a registered trademark of Clark Development Company. WILDCAT! is a registered trademark of Mustang Software. SPITFIRE is a registered trademark of Buffalo Creek Software RBBS-PC is copyright (c) Tom Mack, Capital PC Software Exchange QUICKBBS is copyright (c) Adam Hudson REMOTE ACCESS is copyright (c) Andrew Milner, Continental Software MBBS is copyright (c) Mike Anderson Registration The unregistered library will display "Unregistered copy etc." as part of the signoff message. The registered version eliminates this signoff msg at the time the door is closed. Please see the registration information below. A lot of effort has gone into C-KIT, to make sure it would operate reliably and with little effort on the part of the door author. If you find the program of use, please register it and help support the Shareware method of program distribution. Registering will also help fund further development of the libraries. C-KIT is being distributed as Shareware. The registration includes: ∙ A disk with the latest version of C-KIT, registered to you. . Some small utility programs for easy door testing w/source. ∙ Self-Registration program for future releases of C-KIT ∙ Technical support via electronic mail . A LARGE memory model of C-KIT. (download from Data-Comp BBS) (The LARGE model will also work as a HUGE model) . Access to source code for reading other system files as they become available. All PCBoard source files are now available. For more information see the addresses, phone numbers listed at the end of this document. Global Variables Global Functions/Variable Naming Conventions The C-KIT Library defines a number of variables and functions in the c-kit header file. These have to be made public for the linker to be able to resolve references to them. Beginning in C-KIT 2.0 ALL functions/variables available from the library begin with the prefix "ck_". This will help prevent any naming conflicts with other globals in your source code. Knowing that all C-KIT's names begin with "ck_", you can prevent any collisions with the public names contained in the library. If this is of little concern to you or if you do not like the names used in the library because of this, then you can simply re-define the names to any name you desire. OLDCKIT.H does exactly this for previous users of the library. OLDCKIT.H re-defines the new names to the old names used in the library. If you included OLDCKIT.H in your present source code, then the new library names would work with no other changes to your present source code. Example: Name desired Library Name ======= =========== ============ #define s_puts ck_s_puts #define DUMP_USER ck_DUMP_USER #define color ck_color #define newline ck_newline #define get_cmdline ck_get_cmdline These would cause the compiler to reference the new name for all references to old name. do { color(green); s_puts("Command? ", NULL); get_cmdline(); /* read input into 'cmdline' */ newline(); } while( (DUMP_USER != TRUE) && ( strlen(cmdline) == 0 )); See OLDCKIT.H and CKITDEMO.C, CKITDEMO.H. NOTE: The ONLY variable that does not have the "ck_" prefix is the progname[]; array name in the CKIT.H file. Global Variables Global Variables used by all BBS systems The C-KIT Library defines a number of variables in the ckit.h header file. Through proper use, these variables allow the programmer to customize the C-KIT Library functions to meet particular application program's needs. ck_DUMP_USER ------------------------------------------------------------------- Defined As: short ck_DUMP_USER; Description: This variable will be set if the user hangs up, his/her time runs out, carrier is lost, or if the sysop wants to return the user to the BBS system using function key F8. You should check this flag in all major loops in the door program. ck_FORCEOFFHOOK ------------------------------------------------------------------- Defined As: short ck_FORCEOFFHOOK Description: This variable should be set to TRUE or FALSE in the CKIT.H file. If this variable is TRUE, the modem will be placed OFF-HOOK if carrier is dropped in the door before returning to the system. If FORCEOFFHOOK is false, the door will not take the modem off-hook. See CKIT.H ck_USERFILE ------------------------------------------------------------------- Defined As: short ck_USERSFILE Description: This variable should be set to TRUE or FALSE in the CKIT.H file. If this variable is TRUE, C-KIT will open the Users file and those variables will be available. If not, only the PCBOARD.SYS file will be opened and the user information will not be available. See CKIT.H. ck_option ------------------------------------------------------------------ Defined As: unsigned char ck_option; Description: This variable is set to indicate how the user was logged off the system. There are 5 macro's in the CKIT header file that describes each. #define EXITDOOR 0 Normal door exit #define NOCARRIER 1 Dropped carrier* #define TIMEOUT 2 Keyboard timeout* #define SYSOP_O 3 Sysop request* #define SYSTEMTIME 4 System time expired* #define LOGOFF 5 User logged off * These are normally handled internally by C-KIT COMPATIBILITY Global Variables ck_silent pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: short ck_silent; Description: This variable when TRUE will prevent keyboard timeout beeps from being sent to the local console. It can be controlled via your program. ck_NO_FKEYS pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: short ck_NO_FKEYS; Description: This variable when TRUE will disable the local sysop keyboard F-keys and ALT keys except for ALT-H. Default is FALSE. (F-keys enabled) ck_NOSYSTEM pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: short ck_NOSYSTEM; Description: This variable when TRUE will tell open_door() to not attempt a file open but to read it's information from a data structure. Used for supporting BBS's not supported by C-kit. See open_door() for details. ck_logoff_color pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: short ck_logoff_color; Description: This variable used to specifiy the color of the exit_msg[] string. (See below). See the ckit.h file for colors available. Example: ck_logoff_color = (green). NOTE: If not specified, the default color is violet. ck_exit_msg pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: char ck_exit_msg[40]; Description: THIS VARIABLE IS NO LONGER AVAILABLE IN CKIT2.0 PLEASE SEE **ck_logoff_msgs. ck_logoff_msg pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: char ck_logoff_msg[40]; Description: THIS VARIABLE IS NO LONGER AVAILABLE IN CKIT2.0 PLEASE SEE **ck_logoff_msgs. COMPATIBILITY Global Variables ck_display pcboard.sys ------------------------------------------------------------------ Defined As: short ck_display; Description: This variable is set to indicate the status of the local BBS display. file. TRUE/FALSE 0 = No, 1 = yes. Useful with 12.0 - > 14.x pcboard.sys usage only ck_printer pcboard.sys ------------------------------------------------------------------ Defined As: short ck_printer; Description: This variable is set to indicate the status of the BBS printer. TRUE/FALSE 0 = No, 1 = yes. Useful with 12.0 - > 14.x pcboard.sys usage only ck_pagebell pcboard.sys ------------------------------------------------------------------ Defined As: short ck_pagebell; Description: This variable is set to indicate the status of the BBS pagebell. TRUE/FALSE 0 = No, 1 = yes. Useful with 12.0 - > 14.x pcboard.sys usage only ck_callalarm pcboard.sys ------------------------------------------------------------------ Defined As: short ck_callalarm; Description: This variable is set to indicate the status of the BBS caller alarm. TRUE/FALSE 0 = No, 1 = yes. Useful with 12.0 - > 14.x pcboard.sys usage only ck_PCB door.sys pcboard.sys wildcat! dorinfx.def ------------------------------------------------------------------ Defined As: short ck_PCB; Description: This variable is set to indicate whether C-KIT found a PCBoard.sys file. TRUE/FALSE 0 = No, 1 = yes. ck_GAP door.sys pcboard.sys wildcat! dorinfx.def ------------------------------------------------------------------ Defined As: short ck_GAP; Description: This variable is set to indicate whether C-KIT found a door.sys file. TRUE/FALSE 0 = No, 1 = yes. ck_PCB12 door.sys pcboard.sys wildcat! dorinfx.def ------------------------------------------------------------------ Defined As: short ck_PCB12; Description: This variable is set to indicate whether C-KIT found a PCBoard version 12.0 pcboard.sys file or not. TRUE/FALSE 0 = No, 1 = yes. COMPATIBILITY Global Variables ck_WILDCAT door.sys pcboard.sys wildcat! dorinfx.def ------------------------------------------------------------------ Defined As: short ck_WILDCAT; Description: This variable is set to indicate whether C-KIT found a WILDCAT callinfo.bbs file or not. TRUE/FALSE 0 = No, 1 = yes. ck_RBBS door.sys pcboard.sys wildcat! dorinfx.def ------------------------------------------------------------------ Defined As: short ck_RBBS; Description: This variable is set to indicate whether C-KIT found a RBBS type DORINFOx.DEF file or not. TRUE/FALSE 0 = No, 1 = yes. ck_GENERIC any BBS system ------------------------------------------------------------------ Defined As: short ck_GENERIC; Description: This variable is set to indicate whether C-KIT found a GENERIC.SYS file. TRUE/FALSE 0 = No, 1 = yes. If ck_GENERIC is TRUE you, the door author, should stop and ask the user for his/herfirst and last name. C-kit no longer does this for you. if(GENERIC) { sprintf("\nPlease enter first and last name (MAX 25) ->"); get_cmdline_raw(45); strncpy(ck_fullname, cmdline, 25); } ck_graphics pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: short ck_graphics; Description: This variable is set to indicate the status of the user graphics mode. Supports ANSI X3.64 standard commands. TRUE/FALSE 0 = No, 1 = yes. ck_non_ibm pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: short ck_non_ibm; Description: This variable is set to indicate whether the caller is using 7 bits instead of 8 bits. Using 7 bits doesn't allow for IBM graphic characters above 128 to be displayed correctly. TRUE/FALSE 0 = No, 1 = yes. ck_error_connection pcboard.sys door.sys wildcat! ------------------------------------------------------------------ Defined As: short ck_error_connection; Description: This variable is set to indicate the status of the modem error_connection. TRUE/FALSE 0 = No, 1 = yes. COMPATIBILITY Global Variables ck_local pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: short ck_local; Description: This variable is set to indicate the status of the local/remote operation of door. TRUE/FALSE 0 = No, 1 = yes. ck_expert pcboard.sys door.sys ------------------------------------------------------------------ Defined As: short ck_expert; Description: This variable is set to indicate the status of the expert/novice mode of user. TRUE/FALSE 0 = No, 1 = yes. ck_event_active pcboard.sys ------------------------------------------------------------------ Defined As: short ck_event_active; Description: This variable is set to indicate the status of the system event. TRUE/FALSE 0 = No, 1 = yes. Useful with 14.x pcboard.sys usage only ck_event_slide pcboard.sys ------------------------------------------------------------------ Defined As: short ck_event_slide; Description: This variable is set to indicate whether the system event can be moved or not. TRUE/FALSE 0 = No, 1 = yes. Useful with 14.x pcboard.sys useage only ck_sysop_next pcboard.sys ------------------------------------------------------------------ Defined As: char ck_sysop_next[2]; Description: This C string indicates the status of the Sysop Next flag. N = sysop next, X = exit to system, space = nothing pending. Useful with 12.0 - > 14.x pcboard.sys usage only ck_netchat pcboard.sys ------------------------------------------------------------------ Defined As: char ck_netchat[2]; Description: This C string indicates the status of the the user's netchat. U = Unavailable, A = available. Useful with 12.0 - > 14.x pcboard.sys usage only ck_mem_msg pcboard.sys 14.5 ------------------------------------------------------------------ Defined As: long ck_mem_msg; Description: Memorized message pointer. This is in it's raw form. To use it, you will need to convert from QBasic single (MKS$) to IEEE long. Conversion routines are available on the support BBS. COMPATIBILITY Global Variables ck_aport pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: char ck_aport[2]; Description: This C string is an ASCII string of the com port in use as determined. See also port. ck_bps_open pcboard.sys door.sys wildcat! ------------------------------------------------------------------ Defined As: char ck_bps_open[6]; Description: This C string is an ASCII string of the BBS's DTE to modem baud rate. Not available with PCBoard 12.0 ck_baud_rate pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: char ck_baud_rate[6]; Description: This C string is an ASCII string of the callers baud rate. (DCE rate) ck_uart_base pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: short ck_uart_base; Description: This contains the UART's base address that C-KIT is currently using either as the default or passed by the PORT command. ck_irq pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: short ck_irq; Description: This contains the IRQ that C-KIT is currently using either as the default or passed by the PORT command. ck_firstname pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: char ck_firstname[16]; Description: This C string is an ASCII string of the caller first name. ck_password pcboard.sys door.sys wildcat! ------------------------------------------------------------------ Defined As: char ck_password[13]; Description: This C string is an ASCII string of the caller password. ck_fullname pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ defined As: char ck_fullname[26]; Description: This C string is an ASCII string of the caller fullname. COMPATIBILITY Global Variables ck_page_length pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: BYTE ck_page_length; Description: Page length of user. This information is not available with PCBoard 12.0 so there is a default of 23. The door author can adjust as desired. This is also used by display_file(). Setting to 0 equals continous. (NON-STOP). ck_language pcboard.sys ------------------------------------------------------------------ defined As: char ck_language[5]; Description: This C string is an ASCII string of the caller language. Space = English ck_time_logged pcboard.sys door.sys wildcat! ------------------------------------------------------------------ defined As: char ck_time_logged[6]; Description: This C string is an ASCII string of the time caller logged onto the BBS. ck_event_time pcboard.sys door.sys ------------------------------------------------------------------ defined As: char ck_event_time[6]; Description: This C string is an ASCII string of the system event time of the BBS as HH:MM. Not available with PCBoard 12.0 ck_time_on pcboard.sys ------------------------------------------------------------------ Defined As: short ck_time_on; Description: This variable indicates the time in minutes past midnight the user logged on. ck_prev_used pcboard.sys ------------------------------------------------------------------ Defined As: short ck_prev_used; NOTE: N/A for PCBoard 12.0 Description: This variable indicates the time in minutes used in previous calls today. ck_user_record pcboard.sys door.sys wildcat! ------------------------------------------------------------------ Defined As: unsigned ck_short user_record; Description: This variable holds the user record number. ck_dload_limit pcboard.sys ------------------------------------------------------------------ Defined As: short ck_dload_limit; Description: This variable holds the user's allowed dload Kbytes on the system. COMPATIBILITY Global Variables ck_time_limit pcboard.sys ------------------------------------------------------------------ Defined As: short ck_time_limit; Description: This variable holds the user BBS system time limit in minutes. ck_time_credit pcboard.sys ------------------------------------------------------------------ Defined As: short ck_time_credit; Description: This variable holds the time the user has been given (pos or neg.) that will be added to pcboard.sys when returned to the bulletin board. ck_time_credit_old pcboard.sys ------------------------------------------------------------------ Defined As: short ck_time_credit_old; Description: This variable holds the time credit in minutes (pos or neg.) that was originally found in the pcboard.sys when the door was opened. This will be added with the time_credit when the door is closed. ck_time_added pcboard.sys ------------------------------------------------------------------ Defined As: short ck_time_added; Description: This variable holds the area user time added so far in minutes. ck_min_left pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: short ck_min_left; Description: This variable holds the user time left on system at the time the door was opened. (static). If you want the time remaining in the door, you would need to call the mins_left_system() procedure. ck_min_remaining door.sys ------------------------------------------------------------------ Defined As: char ck_min_remaining[6]; Description: This is the same thing as min_left. It is available as a string only if door.sys is used. See min_left above. ck_sec_remaining door.sys ------------------------------------------------------------------ Defined As: char ck_sec_remaining[6]; Description: This variable holds the seconds left on system at the time the door was opened. (static). If you want the time remaining in the door, you would need to call the mins_left_system() procedure. COMPATIBILITY Global Variables ck_port pcboard.sys door.sys wildcat! ------------------------------------------------------------------ Defined As: short ck_port; Description: This variable holds the com port in use. Equal to 0 if local mode. ck_node[] pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: char ck_node[3]; NOTE: N/A for PCBoard 12.0 Description: This string holds the node in use. Equal to space if no network active. *ck_conferences door.sys wildcat! ------------------------------------------------------------------ Defined As: char *ck_conferences; Description: This a pointer to a string of conferences/forums the user is registered in. ck_parity door.sys wildcat! ------------------------------------------------------------------ Defined As: short ck_parity; Description: Represent the ASCII character of parity in use. Note this NOT a string. It will either be ASCII 7 (0x37) or 8 (0x38). ck_protocol pcboard.sys door.sys wildcat! ------------------------------------------------------------------ Defined As: char ck_protocol[15] Description: String containing the users current protocol setting. PCBoard/GAP/SPITFIRE will only list the 1st char. of the protocol, WILDCAT! will give the entire protocol name. ck_security_level door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: char ck_security_level[5] Description: String containing the users security level. See also ck_user.sec below ck_current_conf door.sys ------------------------------------------------------------------ Defined As: short ck_current_conf; Description: Conference number user just exited from to door. ck_caller_bday door.sys wildcat! ------------------------------------------------------------------ Defined As: char ck_caller_bday[8]; Description: String containing the callers birthday. as MM/DD/YY. Not available with PCBoard systems. COMPATIBILITY Global Variables ck_main_dir door.sys ------------------------------------------------------------------ Defined As: char ck_main_dir[80]; Description: String containing the path to the MAIN directory wherever the users file is located. ck_gen_dir door.sys ------------------------------------------------------------------ Defined As: char ck_gen_dir[80]; Description: String containing the path to the GEN directory. ck_sysop_name door.sys dorinfox.def ------------------------------------------------------------------ Defined As: char ck_sysop_name[15]; Description: String containing the sysop's first name. ck_sysop_alias door.sys ------------------------------------------------------------------ Defined As: char ck_sysop_alias[15]; Description: String containing the sysop's alias name. ck_ansi_ng door.sys ------------------------------------------------------------------ Defined As: short ck_ansi_ng; Description: ANSI supported and caller using NG mode. TRUE/FALSE 0 = No, 1 = yes. ck_record_lock door.sys ------------------------------------------------------------------ Defined As: short ck_record_lock; Description: User record locking. TRUE/FALSE 0 = No, 1 = yes. ck_default_color door.sys ------------------------------------------------------------------ Defined As: char ck_default_color[2]; Description: String containing system's default color ck_last_called door.sys ------------------------------------------------------------------ Defined As: char ck_last_called[6]; Description: String containing user time date called. HH:MM. ck_last_file_scan door.sys wildcat! ------------------------------------------------------------------ Defined As: char ck_last_file_scan[9]; Description: String containing user last new files scan as MM/DD/YY. COMPATIBILITY Global Variables ck_daily_files door.sys wildcat! ------------------------------------------------------------------ Defined As: char ck_daily_files[4]; Description: String containing number of files user has download so far today. ck_daily_bytes door.sys wildcat! ------------------------------------------------------------------ Defined As: char ck_daily_bytes[4]; Description: String containing number of K bytes user downloaded so far today. ck_total_doors door.sys ------------------------------------------------------------------ Defined As: char ck_total_doors[4]; Description: String containing number of doors user has opened. ck_msgs_left door.sys ------------------------------------------------------------------ Defined As: char ck_msgs_left[4]; Description: String containing total number of messages left by user. ck_max_files door.sys ------------------------------------------------------------------ Defined As: char ck_max_files[4]; Description: String containing Max. number of files allowed. ck_upload_Kbytes door.sys ------------------------------------------------------------------ Defined As: char ck_upload_Kbyte[10]; Description: String containing total "K" bytes uploaded. ck_download_Kbytes door.sys wildcat! ------------------------------------------------------------------ Defined As: char ck_download_Kbyte[10]; Description: String containing total "K" bytes downloaded. ck_dload_total door.sys wildcat! ------------------------------------------------------------------ Defined As: char ck_dload_total[5]; Description: String containing total files downloaded. ck_upload_total door.sys wildcat! ------------------------------------------------------------------ Defined As: char ck_upload_total[5]; Description: String containing total files uploaded. COMPATIBILITY Global Variables ck_monitor_type wildcat! ------------------------------------------------------------------ Defined As: char ck_monitor_type[5]; Description: String containing monitor type MONO/COLOR NOTE: C-KIT will set graphics true/false depending on this setting. see Graphics above. ck_max_sec wildcat! ------------------------------------------------------------------ Defined As: char ck_max_sec[5]; Description: String containing a systems maximum user security level for WILDCAT! systems. ck_high_msg wildcat! ------------------------------------------------------------------ Defined As: char ck_high_msg[10] Description: String containing the users highest message read. ck_name_in_use wildcat! ------------------------------------------------------------------ Defined As: BYTE ck_name_in_use Description: Set to TRUE/FALSE. This is called already_connected in the WILDCAT def. file. ck_door_opened wildcat! ------------------------------------------------------------------ Defined As: short ck_door_opened Description: Which door was opened to run your door. ck_BBSname dorinfox.def ------------------------------------------------------------------ Defined As: char ck_BBSname[63]; Description: Name of the BBS system running the door. ck_pcbsysbuf pcboard.sys ------------------------------------------------------------------ Defined As: BYTE *ck_pcbsysbuf; Description: This is a pointer to the buffer holding the pcboard.sys file read. This buffer will be written back to pcboard.sys when close_door() is called. It is provided so a door author can manipulate any byte in the pcboard.sys file and will in turn be written back to the pcboard.sys file. Global Variables These are part of the structure "ck_user" as defined in the CKIT.H file. All these user structure members are available only if the door author specifies USERFILES True (see above) and the system is PCBoard version 14.x. Some but not all members are available if the author specifies USERFILE True and used with Pcboard version 12.0. If the door author does not specify USERFILE's file TRUE, then do not use this structure. If you plan on using this structure and/or update_user(), you must using WORD alignment when compiling your door program for CKIT < version 2.0. For CKIT versions 2.0 and greater, you must use BYTE alignment. ck_user.name See also fullname ------------------------------------------------------------------ Defined As: char ck_user.name[26]; Description: This C string is an ASCII string of the caller's fullname. ck_user.city ------------------------------------------------------------------ Defined As: char ck_user.city[25]; Description: This C string is an ASCII string of the caller's city, state. ck_user.pwrd ------------------------------------------------------------------ Defined As: char ck_user.pwrd[13]; Description: This C string is an ASCII string of the caller's password. ck_user.bphone ------------------------------------------------------------------ Defined As: char ck_user.bphone[14]; Description: This C string is an ASCII string of the caller's business phone number. ck_user.phone ------------------------------------------------------------------ Defined As: char ck_user.phone[14]; Description: This C string is an ASCII string of the caller's home phone number. ck_user.last_date ------------------------------------------------------------------ Defined As: char ck_user.last_date[7]; Description: This C string is an ASCII string of the caller's last date on system. Format is YYMMDD Global Variables These are part of the structure "ck_user" as defined in the CKIT.H file. Information available from user file. ck_user.last_time ------------------------------------------------------------------ Defined As: char ck_user.last_time[6]; Description: This C string is an ASCII string of the caller's last time on system. Format is HH:MM ck_user.expert See also expert above ------------------------------------------------------------------ Defined As: char user.expert[2]; Description: This C string is an ASCII string of the caller expert mode ( Y or N ) ck_user.protocol ------------------------------------------------------------------ Defined As: char ck_user.protocol[2]; Description: This C string is an ASCII string of the caller protocol type in effect. ck_user.packed_byte ------------------------------------------------------------------ Defined As: BYTE ck_user.packed_byte; Description: This holds the PCBoard packed byte to indicate various user options in the user file. ck_user.filedate see also _last_file_scan ------------------------------------------------------------------ Defined As: char ck_user.filedate[7]; Description: This C string is an ASCII string of the caller last DIR scan. in YYMMDD format ck_user.security ------------------------------------------------------------------ Defined As: BYTE ck_user.security; Description: This variable holds the user security level as determined from USER file. ck_user.total_calls ------------------------------------------------------------------ Defined As: short ck_user.total_calls; Description: This variable holds the user total calls on system. ck_user.page_length see also page_length ------------------------------------------------------------------ Defined As: BYTE ck_user.page_length; Description: This variable holds the user page setting. ck_user.uploads see also upload_total ------------------------------------------------------------------ Defined As: short ck_user.uploads; Description: This variable holds the user total uploads. Global Variables These are part of the structure "ck_user" as defined in the CKIT.H file. Information available from user file. ck_user.dloads see also dload_total ------------------------------------------------------------------ Defined As: short ck_user.dloads; Description: This variable holds the user total downloads. ck_user.dload_bytes see also dload_total ------------------------------------------------------------------ Defined As: double ck_user.dload_bytes; Description: This variable holds the user total DAILY downloaded bytes determined from USER file. This variable is in it's raw Qbasic MKD$. To be of use to C, it needs to be converted from QBASIC real to C's IEEE float. The conversion routines/examples are available from the support BBS. Before changing this variable it should also be converted back to a QBASIC real. ck_user.comment1 ------------------------------------------------------------------ Defined As: char ck_user.comment1[31]; Description: This C string is an ASCII string of the caller user maintained comment. ck_user.comment2 ------------------------------------------------------------------ Defined As: char ck_user.comment2[32]; Description: This C string is an ASCII string of the caller sysop maintained comment. ck_user.time_used ------------------------------------------------------------------ Defined As: short ck_user.time_used; Description: Elapsed time on system. (minutes) ck_user.expire_date ------------------------------------------------------------------ Defined As: char ck_user.expire_date[7]; Description: This C string is an ASCII string of the caller expiration date in YYMMDD format. ck_user.expire_level ------------------------------------------------------------------ Defined As: BYTE ck_user.expire_level; Description: This is the users expired security level read from pcboard users file. Global Variables These are part of the structure "ck_user" as defined in the CKIT.H file. Information available from user file. ck_user.current_conf ------------------------------------------------------------------ Defined As: BYTE ck_user.current_conf; Description: This is the last conference user was in read from pcboard users file. ck_user.conferences ------------------------------------------------------------------ Defined As: BYTE ck_user.conferences[6] Description: This is 5 bytes containing the Bitmaps of the conferences the user is registered in. They are in their "raw" form and will have to be decoded before used and encoded before storing. Routines are available from the support BBS. ck_user.expire_conf ------------------------------------------------------------------ Defined As: BYTE ck_user.expire_conf[6] Description: This is 5 bytes containing the Bitmaps of the conferences the user is registered in after his/her expiration date. They are in their "raw" form and will have to be decoded before used and encoded before storing. Routines are available from the support BBS. ck_user.scan_conf ------------------------------------------------------------------ Defined As: BYTE ck_user.scan_conf[6] Description: This is 5 bytes containing the Bitmaps of the conferences the user is registered in and desires a mail scan. They are in their "raw" form and will have to be decoded before used and encoded before storing. Routines are available from the support BBS. ck_user.dload_total see also dload_total ------------------------------------------------------------------ Defined As: double ck_user.dload_total Description: This variable holds the user total downloaded bytes determined from USER file. This variable is in it's raw Qbasic MKD$. To be of use to C, it needs to be converted from QBASIC real to C's IEEE float. The conversion/example routines are available from the support BBS. Before changing this variable it should also be converted back to a QBASIC real. Global Variables These are part of the structure "ck_user" as defined in the CKIT.H file. Information available from user file. ck_user.upload_total see also dload_total ------------------------------------------------------------------ Defined As: double ck_user.upload_total; Description: This variable holds the user total uploaded bytes determined from USER file. This variable is in it's raw Qbasic MKD$. To be of use to C, it needs to be converted from QBASIC real to C's IEEE float. The conversion/example routines are available from the support BBS. Before changing this variable it should also be converted back to a QBASIC real. ck_user.delete_user ------------------------------------------------------------------ Defined As: char ck_user.delete_user[2]; Description: This C string is an ASCII string of delete user flag. (Y or N) ck_user.last_msg_read see also dload_total ------------------------------------------------------------------ Defined As: long ck_user.last_msg_read; Description: This variable holds the user last message read in the main conference. This variable is in it's raw Qbasic MKS$. To be of use to C, it needs to be converted from QBASIC real to C's IEEE float. The conversion/example routines are available from the support BBS. Before changing this variable it should also be converted back to a QBASIC real. ck_user.last_read see also dload_total ------------------------------------------------------------------ Defined As: long ck_user.last_read[39] Description: This variable array contains the last read message pointers for conferences 0-39. They are in raw Qbasic MKS$. To be of use to C, it needs to be converted from QBASIC real to C's IEEE float. The conversion/example routines are available from the support BBS. Before changing this variable it should also be converted back to a QBASIC real. System Global Variables These variables are available with any BBS system. Some are used for customization of your door program and MUST be defined. Others using are meant to be read only variables available globally. Some are are used in conjuction with high level functions as noted. char progname[] pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: char progname[21]; Description: Set this to your Door program name. It will be display on the status line on the sysop screen. MAXIMUM length is 20 characters! Do not exceed this! NOTE: THIS IS NOT AN OPTION. You must define progname[] even if you do not plan on using it. ck_cmdline[] pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: BYTE ck_cmdline[128] Description: This is used by get_cmdline(), to read the user keyboard input to. Please see the CKITDEMO.C for usage. See Also: ck_get_cmdline(); ck_par[] pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: char ck_par[128]; Description: This is used by get_nextpar(), to parse stacked commands to. Please see CKITDEMO.C for usage. See Also: ck_get_cmdline(), ck_get_nextpar(); ck_scan_code pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: size_t ck_scan_code; Description: This variable will if NONZERO contain the key_code of any NON-STANDARD keys on the IBM keyboard. (F1-F10, PgDn, PgUp etc). The remote user must be in some type of terminal program that will allow passing the keycodes. Qmodem in "DOORWAY" mode is one example. Please see ck_input(), ck_get_cmdline() and ckitdemo.c for examples. See Also: ck_get_cmdline(); ck_key_source pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: short ck_key_source; Description: This variable will a 1 if the input from get_cmdline() came from the LOCAL console or a 2 if it came from a REMOTE console. See Also: ck_get_cmdline(), ck_input() System Global Variables ck_linenum pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: short ck_linenum; Description: This variable be will incremented each time a call to newline() is made. See Also: ck_page_length, ck_newline() ck_logoff_msgs pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: char **ck_logoff_msgs; Description: This is pointer to an array of pointers that will be printed at the time the door is closed. The array of pointers has a length of 6 elements. Which message is printed depends on the value of ck_option. The code looks for an array of pointers to the exit messages and uses the ck_option variable to pick which one to print. This pointer to the array of pointers allows you to define your own array of pointers to the 6 exit messages. This allows the messages to be of any length and which message printed will be based on the value of ck_option (0-5) respectfully. See also the variable ck_option. They must be in this order. Example to create your own log off messages of ANY size. In your source code: char option0[] = "New Returning to system msg, any size\n"; char option1[] = "New CARRIER DROPPED! msg, any size\n"; char option2[] = "New Keyboard Timeout! msg, any size\n"; char option3[] = "New Sysop requests return to BBS msg, any size\n"; char option4[] = "New System time has expired! msg, any size\n"; char option5[] = "New Thanks for calling! msg, any size"; static char *logoffs[6] = { /* create array of ptrs */ option0, option1, option2, option3, option4, option5, }; ck_logoff_msgs = &logoffs[0]; /* Set C-KIT's pointer to custom messages*/ System Global Variables ck_logoff_msgs <cont.> ------------------------------------------------------------------ You do NOT have to define your own log off messages. C-KIT has it's own internal defaults. If you want to change just one individual log off message and leave the rest alone, then you can use the pointer that is initially contained in **ck_logoff_msgs and index to the one you want to change. Doing this will limit the size to the max. indicated for that message. The limits on changing individual logoff internal library messages are: MAX SIZE! ======== option0[40] /* internal "returning to board" msg */ option1[16] /* internal "NO CARRIER!!" msg */ option2[40] /* internal "keyboard timeout" msg */ option3[48] /* internal "sysop request" msg */ option4[36] /* internal "time expired" msg */ option5[40] /* internal "goodbye" msg */ To change only one internal logoff library message, use the pointer that is originally contained in **ck_logoff_msgs. Indexing from it, you can use strcpy() to change it. EXAMPLE: To change only the "returning to board" msg. IN YOUR source code: char exit_msg[40] = "Returning to system\n"; /* Max 40 allocated in lib */ strcpy(*(ck_logoff_msgs), exit_msg); /* Using the orignal pointer, copy new string */ To change only the "goodbye" msg. IN YOUR source code: char logoff_msg[40] = "Thanks for calling\n"; /* Max 40 allocated in lib */ strcpy(*(ck_logoff_msgs + 5), logoff_msg); /* Use the original pointer */ Again, you can provide your own array of pointers and change all the messages to any size desired. Look at the ckitdemo.c, ckitdemo.h. System Global Variables ck_gen_msgs pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ defined as: char **ck_gen_msgs; Description: This is pointer to an array of pointers that are C-KIT's internal messages. The array of pointers has a length of 12 elements. The code looks for an array of pointers to index which message to print. This pointer to the general array of pointers allows you to define your own array of pointers to the 12 internal messages. The messages can be of any length and which message printed will be based their position in the array. The ordering of the array is - 0 - Screen display on message 1 - Event pending warning, time adjusted 2 - Press enter to continue message, used with FORCE_ENTER. 3 - Sysop chat active msg 4 - Sysop chat end msg 5 - Sysop exited to DOS msg 6 - Sysop back from DOS msg 7 - (Enter=none)? msg used in get_defn() and get_defen() 8 - (Enter=yes) msg used in get_defyn() 9 - (Enter=no) msg used in get_defyn() 10 - (Enter) or (Y)es, (N)o, (NS)nonstop? msg used in no_more & display_file 11 - More: - msg used in no_more and display_file ck_gen_msgs = &ckitmsgs[0]; /* Set pointer to custom message ptrs */ You do NOT have to define these messages. C-KIT has it's own internal defaults. If you want to change just one individual message and leave the rest alone, then you can use the pointer that is initially contained in **ck_gen_msgs and index to the one you want to change. Doing this will limit the size to the max. indicated for that message. The limits on changing individual general internal library messages are: MAX SIZE! ======== msg0[18] /* internal "Screen on" msg */ msg1[44] /* internal "Event pending" msg */ msg2[28] /* internal "Enter to cont." msg */ msg3[48] /* internal "Sysop Chat" msg */ msg4[18] /* internal "Chat end" msg */ msg5[42] /* internal "Exit to DOS" msg */ msg6[40] /* internal "Return from DOS" msg */ msg7[14] /* internal "prompt1" msg */ msg8[12] /* internal "prompt2" msg */ msg9[10] /* internal "prompt3" msg */ msg10[38] /* internal "prompt4" msg */ msg11[6] /* internal "More: " msg */ System Global Variables ck_gen_msgs <cont.> ------------------------------------------------------------------ To change only one internal general library message, use the pointer that is originally contained in **ck_gen_msgs. Indexing from it, you can use strcpy() to change it. EXAMPLE: To change only the "Screen display on" msg. IN YOUR source code: char display_msg[18] = "<Screen ON>"; /* Max 18 allocated in lib */ strcpy(*(ck_gen_msgs), display_msg); /* Using the orignal pointer, copy new string */ To change only the "Exited to DOS" msg. IN YOUR source code: char dos_ret_msg[42] = "Sysop exited to DOS\n"; /* Max 42 allocated in lib */ strcpy(*(ck_gen_msgs + 6), dos_ret_msg); /* Use the original pointer */ Again, you can provide your own array of pointers and change all the messages to any size desired. Look at the ckitdemo.c, ckitdemo.h. ck_system_time_HHMMSS[] pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: char ck_system_time_HHMMSS[9]; Description: This string will contain the current system time in the form HH:MM:SS and is available for general use. ck_todays_date_MMDDYY[] pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: char ck_todays_date_MMDDYY[9]; Description: This string will contain the current system date in the form MM:DD:YY and is available for general use. ck_error_msg11[] pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: char ck_error_msg11[40]; Description: Error message used by display_file. If you do not define this, C-KIT will default to it's standard error message. MAX. 40 chars. (not including NULL). ck_chatmode pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: short ck_chatmode; Description: This variable will a 1 (TRUE) if chat mode or a sysop drop to DOS has been active. Use this to re-fresh your screen if needed. It is YOUR responsiblity to de-assert the variable after you have used it. (set to FALSE) System Global Variables ck_DOTS ------------------------------------------------------------------ Defined as: BYTE ck_DOTS; Description: This variable when set to a non-zero value will echo that value (character) to the to the remote/ local screens when using input() or get_cmdline(). For instance, setting ck_DOTS to a '.' will cause dots to be echoed to the screen. Handy for using with passwords etc. Resetting back to a NULL will resume normal operations. Standard Data Types Standard Data Types CKIT.H defines a number of useful data types. BYTE ------------------------------------------------------------------- Defined As: typedef unsigned char BYTE; Description: The BYTE data type is useful in serial communications since it provides an easier and more logical way of handling 8 bit data from UART's used in serial communications. Functions Functions The C-KIT Library contains a variety of functions. They are described as follows: Summary: Presents an exact syntactic model for each of the C-KIT Library functions. Description: Describes a function's purpose and how it is used in an application program. Return Value: Explains any of the possible return values for a C-KIT Library function. See Also: Lists any similar or related C-KIT Library function. Example: Illustrates how a C-KIT Library function could actually be used in an application program. Most function listed in the examples will be simply listed as function(). This may not indicate how they are called. To see how they are prototyped and called go to that function's page. I.E. If open_door is used in an example (other than it's own example) it may be simply refered to as open_door(). In reality open_door is really open_door(char * ...); The library functions are classified as 3 different types. High level, intermediate and low level. Normally a door would not need to make use of any of the functions except the high level functions. These handle and watch all the system timeouts, carrier detects, keyboard timeouts etc. If you need more control, there are other functions available. I will warn you. The lower level function you use, the less it will check for you automatically. Do not use these unless you have to. Functions ck_open_door ------------------------------------------------------------------- Summary: #include "ckit.h" short ck_open_door(); Description: The open door function initializes vectors, reads bbs system information. THIS MUST BE CALLED FIRST! The first pointer should be be the path/name to the system file. The second pointer should be the path/name to the users file, if you designated USERSFILE=TRUE. open_door() will also accept a pointer to a data structure if ck_NOSYSTEM is TRUE. (for pcboard systems only). As long as you have defined USERSFILE = FALSE, C-KIT will not attempt to use the second pointer. Which ever you specify, the PORT:AAAA:X (if used) must be the last parameter passed to open_door();. Close_door MUST be called before exiting program after a call to open_door. See the CKITDEMO.C for more examples. Return Value: Will return NULL is successful, otherwise it will return an error code listed below. See Also: ck_close_door Example: This example assumes the path\filenames passed on the command line. i.e program_name path\filename path\filename port #include "ckit.h" short result; main(int argc, char **argv) { if (argc > 0) { if(!ck_open_door(argv[1], argv[2], argv[3])); <--- NOTE: display_info(); argv[2] and your_main_program(); argv[3] are } else { optional. printf("Error opening door!"); see below. } ck_close_door(); exit(0); } } open_door() returns these codes: 0 ;Successful 1 ;Unable to open BBS system file (pcboard.sys,door.sys etc) 2 ;Problem reading BBS system file 3 ;Unrecognized BBS file type 4 ;Unable to open pcboard USERS file 5 ;Invalid User record or problem seeking to user record 6 ;Problem reading USER record 7 ;PORT command syntax error 8 ;Fossil driver specified but no Fossil driver installed 9 ;Memory allocation problem Functions ck_open_door <cont.> ------------------------------------------------------------------- NOTE: Both PORT and USERSFILE are optional. If a user of your door needed to specify a non-standard port address and IRQ, then the syntax is PORT:AAAA:X where AAAA is the base address and X is the IRQ. It doesn't matter whether PORT:AAAA:X is the second or third parameter (depending on if you were opening the user file) passed to open_door() as long as it is the LAST parameter passed. Note also it does not matter which order on the cmd line the arguments are listed. The only thing that matters is which order they are passed to the open_door() function itself. You could also have the system path as part of a config file for your door. Then you would read your config file and pass the path read from it to open_door() as a string ptr. PORT is optional, and C-KIT will default to standard addresses and irq's if PORT is not used based on the port number read from the BBS file. C-KIT will assume COM1 = 03F8 IRQ 4, COM2 = 02E8 IRQ3, COM3 = 03E8 IRQ4 and COM4 = 02E8 IRQ 3. If the sysop had a different non-standard port address and irq, he could then use the PORT cmd to change the defaults. For this reason, you should include the usage of PORT in your door program and documenation. Below is some examples of how your program would/could be called up and how the open_door() function would be called. Notice PORT is always the second or third (last) argument to be passed if a user of your door program wanted to use it. C-KIT will also support the use of FOSSIL drivers. The syntax for a FOSSIL driver is: PORT:F:P. The 'F' tells C-KIT to use a Fossil driver for it's communications. The 'P' following it tells it which port to use for the Fossil. Example - PORT:F:1, tells C-KIT to use a fossil driver for port 1. YOU AS A DOOR AUTHOR SHOULD ALSO INCLUDE THIS INFORMATION IN YOUR DOOR DOCUMENTATION FILES AND INCLUDE IT IN YOUR CALL TO OPEN_DOOR(). open_door() works like this. It will expect the first pointer to be a string pointer to the BBS system file, always. Next, it checks to see if USERSFILE = TRUE. If so, it will expect the second pointer to be a string pointer to a PCBoard users file. If USERSFILE is FALSE it will not look for a users file. Either case, open_door() will search the stack frame pointers for the word "PORT" for the 2nd and 3rd string pointers passed. If it finds it, it will utilize it. If not, it will use the default port addresses/irq's defined above for the COM port read from the system file. For this reason, open_door() will work whether there is actually a port command being passed or not. You as the door author should provide the users of your door the ability to pass the port command if they are using NON-STANDARD ports. Functions ck_open_door (cont.) ------------------------------------------------------------------- EXAMPLES: Assume door.cfg below is a config file that your door programs reads. This all depends on how or what is desired for your door program. You would need to document in your door documentation what order the cmd line should be for your door program, OR read your config file and pass the system name and path to open_door(). You should also include info about the PORT:AAAA:X in your docs. Here is a short example of reading a config file and passing the system name and path. (Assuming the 1st line in the config file has the system path\name) main(int argc, char **argv) { short handle, bytes_read; char bbssyspath[81]; handle = open(argv[1], O_RDONLY); /* Open config file */ bytes_read = read(handle, bbssyspath, 80); /* Read system path\name */ bbssyspath[bytes_read - 1] = '\0'; /* Null terminate */ close(handle); /* Close config file */ ck_open_door(bbssyspath, argv[2]); /* include arg2 for the PORT cmd */ ck_close_door(); } Your program's cmd line for the above could be any one of the following: doorprgm config.cfg ;Using standard ports doorprgm config.cfg PORT:03E8:5 ;Using non-standard port doorprgm config.cfg PORT:F:1 ;Using a fossil driver on port 1 You may not need or want a config file for your door program so you could just simply have the sysop pass the system infomation on the command line. If this is the case, your program's cmd line could be any of the following: doorprgm c:\wc\callinfo.bbs ;Using standard ports doorprgm c:\wc\callinfo.bbs PORT:03F8:5 ;Using non-standard port doorprgm c:\wc\callinfo.bbs PORT:F:1 ;Using a fossil driver on port 1 Again, you as the door author would explain in your documentation how the sysop would set your door program up depending on how you decide to handle reading the system files. Just be sure and include information about the PORT:AAAA:X and PORT:F:P commands as well. Functions ck_open_door (cont.) ------------------------------------------------------------------- HIGHLY RECOMMEDED!: You should include in your door source code C's atexit() function. Then have it call a function that will test if door_open() has been called or if close_door() has already been called. Then if your program has a runtime error, you will call close_door() so all interrupts vectors can be restored and prevent a system crash. Take a look at ckitdemo.c. EXAMPLE: short OPENED; /* Flag to know if open_door has been called */ short CLOSED; /* Flag to know if close_door has beeb called */ void shut_down(void); /* Shuts door down if normal or error occurs. */ main(int argc, char **argv) { open_door(argv[1], argv[2]); OPENED = TRUE; /* Door has been opened */ atexit(shut_down); . . . } /**************************************************************************** * Close door, reset vectors etc. * * Need in case of a run time error occurs in door * * and to check if a call to close_door needs to be made. * ****************************************************************************/ void shut_down(void) { if(OPENED && !CLOSED) { close_door(); CLOSED = TRUE; } } Functions ck_open_door (cont.) ------------------------------------------------------------------- Another way open_door() can be used is thru the use of a data structure defined as: typedef struct ckitgeneric { char port[6]; /* COM:? */ short min_left; /* minutes left */ }; This allows you to support BBS programs in your door program that are not supported directly by Ckit. To do this, you would read the BBS system file yourself. Obtain the necassary information for the data structure, set ck_NOSYSTEM = TRUE, then call open_door(). Below is a short example of reading a WWIV file. (WWIV is not directly supported by CKIT). typedef struct ckitgeneric { char port[6]; /* COM:x (COM0: is local) */ short min_left; /* minutes left */ }; struct ckitgeneric ck_gen; /* You can name this whatever you want */ char *ptr; if(WWIV) { open_file(bbs_system_file); read_file(bbs_system_file); setup_ck_gen(); /* set up data structure */ ck_NOSYSTEM = TRUE; ptr = &bbs_system_file); } else { ptr = &bbs_system_file; ck_NOSYSTEM = FALSE; } open_door(ptr, argv[2]); (2nd arg is for passing the PORT:AAAA:X cmd) Take a look at the ckitdemo.c file for a complete example. Functions ck_close_door high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_close_door(void); Description: The close door function resets vectors, closes files opened and prints the log off message. THIS MUST BE CALLED LAST and ONLY after open_door(). Close_door MUST be called before exiting program after a call has been made to open_door. Not doing so will certainly cause a system lock up. See above for using C's atexit() function. Version 2.0 and above, close_door will check if open_door has been called or if close_door() has already been called to help further prevent any system hangups. Return Value: No value is returned. See Also: ck_open_door. Example: #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { ck_open_door("d:\wc\callinfo.bbs"); . . . . your door program . . ck_close_door(); }; }; Functions ck_update_user PCBOARD 14.5 only high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_update_user(); Description: The update user will accept a POINTER to the user structure member to update. See the user structure above. This function will only work for PCBoard 14.5 and USERSFILE must be set TRUE. C-KIT will update the user file when the door is closed. If you do not want C-KIT to update the user record after a change has been made set USERSFILE = FALSE before calling close_door(); If you use this function you should set the compiler to use WORD alignment for C-kit v.2.01 and below. NOTE: IN VERSION 2.08 AND ABOVE, YOU NEED TO USE BYTE ALIGNMENT! Return Value: No value is returned. See Also: ck_user structure Example: Change user security and comment1 field. MOTICE THE & BELOW!. You MUST pass the address of the member to update in the user structure. #include "ckit.h" main(int argc, char **argv) { USERSFILE = TRUE; static char new_comment[] = "ckit_user"; if (argc > 1) { ck_open_door(argv[1], argv[2]); (pass system file and PORT cmd) . . . ck_usersecurity = 50; ck_update_user(&ck_usersecurity); strcpy(ck_usercomment1, new_comment); ck_update_user(&ck_usercomment1); . . . ck_close_door(); }; }; Functions ck_s_puts high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_s_puts(char *); Description: The s_puts function displays a single NULL termintated (C string) to the local and remote console. It expects a pointer to the string of type BYTE or char to be displayed. It will not handle ANSI. See ck_s_putstd() for ANSI and other usage. Return Value: No value is returned. See Also: s_printf, ck_s_putv, ck_s_putc, ck_s_putsn Example: #include "ckit.h" static BYTE string[] = "This is a test"; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); /* pass system file(s) */ . . . ck_s_puts(string); ck_s_puts("This is also a test"); . . . ck_close_door(); }; }; Functions ck_s_putstd high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_s_putstd(char *); Description: The s_putstd function displays a single NULL termintated (C string) to the local and remote console. It expects a pointer to the string of type BYTE or char to be displayed. This function is identical to s_puts except it uses std output. This function should be used when ANSI code, or CTRL chars are needed to be sent to the local and remote consoles. Return Value: No value is returned. See Also: s_printf, ck_s_putv, ck_s_putc, ck_s_putsn Example: Use s_putstd() to change background/foreground colors #include "ckit.h" #define cyanblue 0 #define yellowbrown 1 #define redgreen 2 #define redcyan 3 #define cyanred 4 #define cyanmagenta 5 #define bluegrey 6 static char *ansi_color[8] = { "\33[0;1;36;44mCyan on Blue\33[40m" "\33[44m\33[33;43mYellow on Brown\33[40m" "\33[43m\33[0;31;42mRed on Green\33[40m" "\33[42m\33[46mRed on Cyan\33[40m" "\33[46m\33[1;36;41mCyan on Red\33[40m" "\33[41m\33[45mCyan on Magenta\33[40m" "\33[45m\33[0;34;47mBlue on Grey\33[0m" }; main(int argc, char **argv) { if (argc > 0) { ck_open_door(argv[1]); /* pass system file(s) */ . . . ck_s_putstd(ansi_color[cyanblue]); ck_s_putstd(ansi_color[yellowbrown]); ck_s_putstd(ansi_color[redgreen]); ck_s_putstd(ansi_color[redcyan]); ck_s_putstd(ansi_color[cyanred]); ck_s_putstd(ansi_color[cyanmagenta]); ck_s_putstd(ansi_color[bluegrey]); . . . ck_close_door(); }; }; Functions ck_s_putv high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_s_putv(); Description: The s_putv function displays a single NULL terminated (C string) to the local and remote console. It expects a variable argument of pointer(s) to the string(s) of type BYTE or char to be displayed. The list of pointers MUST end with a NULL pointer!. Not doing so will most likely either cause garbage to printed or even a hang-up. Return Value: No value is returned. See Also: s_printf, ck_s_puts, ck_s_putc, ck_s_putsn Example: This example prints 2 strings with the pointer list terminated with a NULL pointer. #include "ckit.h" static BYTE string[] = "This is a test"; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); /* pass system file(s) */ . . . static BYTE string[] = "This is a test"; ck_s_putv(string, "This is also a test", NULL); . . . ck_close_door(); }; }; NOTE: an alternative to using s_putv would be to include the function s_printf() below in your source code. You could use this function the same as you would printf(); This function has already been protyped in CKIT.H Functions s_printf high level ------------------------------------------------------------------- Summary: #include "ckit.h" void s_printf(char *,...); Description: The s_printf function is used to format an output to be sent to the local and remote console. It is exactly the same as the cprintf() function in C. To use it, you must include the source code listed below in your door program since s_printf() is NOT an actual part of the C-KIT librarys. NOTE: if you want to send ANSI strings, change the s_puts in the s_printf function to s_putstd or create another std_printf function using s_putstd as the output. Return Value: No value is returned. See Also: s_printf, s_puts, s_putv INCLUDE THIS SOURCE CODE IN YOUR DOOR PROGRAM TO USE S_PRINTF! THE FUNCTION HAS ALREADY BEEN PROTOTYPED IN CKIT.H MODIFY AS YOU NEED. /**************************************************************************** * Printf() function for sending output to port * ****************************************************************************/ void s_printf(char *s_format,...) { va_list arg_pointer; char buffer[82]; /* string buffer for 81 chars */ va_start(arg_pointer, s_format); vsprintf(buffer, s_format, arg_pointer); s_putstd(buffer); /* change to s_putstd() for ANSI */ va_end(arg_pointer); } Example: /**************************************************************************** * sending a string out the port using s_printf() * ****************************************************************************/ #include "ckit.h" short number 34; main(int argc, char **argv) { if (argc > 1) { ck_open_door("c:\rbbs\dorinfo1.def", argv[1]); . . . s_printf("Hello, %s. The number is %d.", firstname, number); . . . ck_close_door(); }; }; Functions ck_s_putsn high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_s_putsn(char *); Description: The s_putsn function displays a single NULL terminated (C string) to the local console only. It expects a pointer to the string of type BYTE or char to be displayed. Return Value: No value is returned. See Also: s_printf, ck_s_putv, ck_s_putc, ck_s_putstd Example: #include "ckit.h" static BYTE string[] = "This is a test"; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1], argv[2]); (include arg2 for the PORT cmd) . . . static BYTE string[] = "This is a test"; ck_s_putsn(string); ck_s_putsn("This is also a test"); . . . ck_close_door(); }; }; Functions ck_s_putc high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_s_putc(BYTE); Description: The s_putc function displays a single BYTE or char to the local and remote console. Return Value: No value is returned. See Also: s_printf, ck_s_puts, ck_s_putc. Example: This example prints a single BYTE (ASCII A) to local and remote console. #include "ckit.h" BYTE byte_to_send = 0x41; short handle, bytes_read; char pcbsyspath[81]; main(int argc, char **argv) { if (argc > 1) { handle = open(argv[1], O_RDONLY); bytes_read = read(handle, pcbsyspath, 80); pcbsyspath[bytes_read - 1] = '\0'; close(handle); open_door(pcbsyspath, argv[2]); (include arg2 for the PORT cmd) ck_s_putc(byte_to_send); ck_close_door(); }; }; Functions ck_newline high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_newline(void); Description: The newline function sends a Carriage Return/ Line Feed to the local and remote console. Increments ck_linenum. Return Value: No value is returned. See Also: s_printf, ck_s_puts, ck_s_putc, ck_linenum Example: This example prints single CR/LF to local and remote console. #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]), argv[2]); . . . ck_newline(); . . . ck_close_door(); }; }; Functions ck_clear_row high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_clear_row(short); Description: The clear_row function clears a given row on screen of the local and remote console. (row = 1 - 24). Used only if caller is in GRAPHICS or ansi_ng mode. Return Value: No value is returned. See Also: ck_clear_eol, ck_clr_screen. Example: This example prints a string on a line, then erases the string. #include ckit.h char prompt1 = "Enter filename to view: "; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1], argv[2]); (pass system file and port cmd) ck_pos_cursor(10, 1); ck_s_puts(prompt1); ck_pos_cursor(11, 1); ck_s_puts("Ready to clear above row, press a key"); while(!(wait_keypress())) { }; ck_clear_row(10); /* clear row 10 */ ck_newline(); ck_close_door(); }; Functions ck_clear_eol high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_clear_eol(void); Description: The clear_eol function clears to the end of line from current cursor position. Used only if caller is in GRAPHICS or ansi_ng mode. Return Value: No value is returned. See Also: ck_clear_eol, ck_clr_screen. Example: This example clears to end of line on screen of local and remote console. #include ckit.h char prompt1 = "Enter filename to view: "; main(int argc, char **argv) { if (argc > 1) { ck_open_door("c:\wildcat\callinfo.bbs", "PORT:03E8:5"); ck_newline(); ck_s_puts("Press a key to clear end of line below"); ck_newline(); ck_s_putv(prompt1, "\r", NULL); while(!(wait_keypress())) { }; ck_clear_eol(); ck_newline(); ck_close_door(); }; }; Functions ck_clr_screen high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_clr_screen(void); Description: The clr_screen function clears entire screen of local and remote console in either ASCII, GRAPHIC, or ansi_ng mode. Return Value: No value is returned. See Also: ck_clear_screen. Example: This example clears screen of local/remote console. #include ckit.h main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_clr_screen(); . . . ck_close_door(); }; }; Functions ck_clear_screen high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_clear_screen(void); Description: The clear_screen function clears entire screen of local console including status line. Return Value: No value is returned. See Also: ck_clr_screen. Example: This example clears screen of local console. #include ckit.h main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_clear_screen(); . . . ck_close_door(); }; }; Functions ck_pos_cursor high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_pos_cursor(short, short); Description: The pos_cursor function positions cursor at row, column using ANSI. Caller must be in GRAPHICS, or ansi_ng mode. If not no action will take place. row = 1 to 25, column = 1 to 80. C-KIT will not let the local screen position cursor in status line area. Return Value: No value is returned. Example: This example positions cursor at row 10, column 15 on the local/remote consoles. #include "ckit.h" short row = 10; short column = 15; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_pos_cursor(row, column); . . . ck_close_door(); }; }; Functions ck_set_r_c high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_set_r_c(short, short); Description: The set_r_c function positions cursor at row, column using BIOS on the local screen. row = 1 to 25 (23), column = 1 to 80. C-KIT will not let the cursor be placed in the status line area of local screen. Return Value: No value is returned. Example: This example positions cursor at row 5, column 1 on the local console. #include "ckit.h" short row = 5; short column = 1; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_set_r_c(row, column); . . . ck_close_door(); }; }; Functions ck_back_space high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_back_space(short); Description: The back_space function backspaces cursor short number of spaces or to the 1st char in row, whichever is 1st. This is a destrutive backspace. Return Value: No value is returned. Example: This example backspaces cursor over the prompt and on the user's input local/remote consoles. #include ckit.h char prompt1 = "Enter filename to view: "; main(int argc, char **argv) { if (argc > 1) { ck_open_door("c:\pcb\pcboard.sys", "PORT:02E8:4"); ck_s_puts("\r\nReady to test back_space()"); ck_s_puts("Press a key when ready"); ck_newline(); while(!(wait_keypress())) { }; ck_color(yellow); ck_s_puts(prompt1); ck_color(red); ck_get_cmdline(); ck_back_space(strlen(prompt1) + strlen(cmdline)); ck_close_door(); }; Functions ck_color high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_color(short); Description: The color function selects color to use using ANSI. Caller must be in GRAPHICS mode. If not, no action is taken. ck_color will only set the forground color and leave the background color as it was. Return Value: No value is returned. See Also: Color macros above in macro section used with C-KIT Example: This example sets color to red on the local/remote consoles.(see color macros in ckit.h) #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_color(red); . . . ck_close_door(); }; }; Functions ck_set_ANSI high level ------------------------------------------------------------------- Summary: #include "ckit.h" short ck_set_ANSI(short) Description: Allows manual program changing of ANSI capability. Excepts either TRUE/FALSE. Normally when C-kit first opens a system file it determines from the file whether the user wants ANSI control, (ansi_NG will be set, GRAPHICS FALSE) OR if they wanted ANSI control with graphics (ansi_NG false, GRAPHICS TRUE). This information is not available for generic.sys. ck_set_ANSI allows people using the generic.sys file to select ANSI control and/or ANSI control with graphics. Return Value: Returns whatever is passed to it. See Also: ck_graphics, ck_ansi_ng Example: This example turns on ANSI capability without graphics. #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ansi_ng |= TRUE; /* Set ansi_ng */ graphics &= FALSE; . . . ck_set_ANSI(ansi_ng | graphics); . . . ck_close_door(); }; }; Functions ck_get_cmdline high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_get_cmdline(void); Description: Read a line of input (max 128 bytes). Echo to screen, leave cursor after the last key typed before C/R. Automatically checks for time_left, carrier. Calls ck_input() and reads into array *cmdline, automatically maps input to Uppercase. Will also set key_source to source of input. *defined in CKIT.H. This function is the one you would normally use for ALL user input. ALL other input functions are intermediate or low level functions. Setting ck_DOTS = char will cause char to be echoed to the remote/local console. Filters all ASCII control charactors below 31 dec. out. Return Value: No value is returned. See Also: ck_input, ck_get_nextpar, ck_key_source, ck_wait_keypress Example: This example reads keyboard from local/remote console into array get_cmdline[]. It also checks for any scan_codes receieved. See Ckitdemo.c also. #include "ckit.h" main(int argc, char **argv) { ck_open_door(argv[1]); do { ck_newline(); display_time(); ck_color(green); ck_s_puts("Command? "); ck_get_cmdline(); /* read input into 'cmdline' */ } while((ck_DUMP_USER != TRUE) && (strlen(ck_cmdline) == 0) \ && (ck_scan_code == 0)); } if (ck_DUMP_USER == TRUE) { ck_close_door(); exit(1); } if (ck_scan_code != NULL) { ck_color(white); read_scancode(); ck_newline(); } if (ck_get_nextpar()) { /* scan next parameter from cmdline into par */ ck_newline(); /* process commands */ switch ( par[0] ) { case 'A': ansi_demo(); break; default: ck_color(magenta); ck_s_putv("(",par,") is not allowed! Try again:", NULL); *ck_cmdline = NULL; } } Functions ck_wait_keypress high level ------------------------------------------------------------------- Summary: #include "ckit.h" short ck_wait_keypress(void); Description: Waits for any keypress. Does not wait for a C/R. Autochecks for CARRIER, TIMEOUTS etc. Returns ASCII code of key pressed or TRUE if ck_DUMP_USER goes TRUE otherwise it will return FALSE. Will also return TRUE if extended key is pressed. Will not do so if a sysop function key is pressed. Useful for "hot_key" applications. Will also set key_source to proper value. Return Value: ASCII code of keypressed or TRUE, FALSE See also: ck_check_CR, ck_check_keypress, ck_input, ck_get_cmdline Example: This example will wait until a keypress or ck_DUMP_USER. #include "ckit.h" prompt2 = ""Press any key to continue"; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_color(yellow); ck_newline(); ck_s_puts(prompt2); while(!(ck_wait_keypress())) { }; ck_back_space(strlen(prompt2) + 1); . . . ck_close_door(); }; }; Functions ck_force_enter high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_force_enter(void); Description: Prompts " Press Enter to continue: ", wait for C/R, automatic carrier, time_left and sysop checks. Return Value: NONE Example: This example displays a string then prompts and forces user to press C/R to continue. #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_color(yellow); ck_s_puts("Display this string\r\n"); ck_force_enter(); . . . ck_close_door(); }; }; Functions display_time high level ------------------------------------------------------------------- Summary: #include "ckit.h" void display_time(void); Description: Displays (xxxx used, xxx left). In CKIT2.0 and above, this function is not in the library. Instead, using the source code below will do the same thing as previous display_time(). Return Value: NONE See Also: mins_left_system(), system_time_used() Example: See CKITDEMO.C also #include "ckit.h" main(int argc, char **argv) { ck_open_door(argv[1]); if (argc > 1) { ck_open_door(system_ptr, port_cmd_ptr); . . . display_time(); . . . }; void display_time(void) { color(yellow); ck_s_puts("("); ck_color(green); s_printf("%d used, ", system_time_used()+prev_used); ck_color(red); s_printf("%d left", mins_left_system()+time_credit); ck_color(yellow); ck_s_puts(") "); } Functions ck_get_cmdline_raw high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_get_cmdlinaw(short); Description: Same as get_cmdline() above but erases prompt of after input and user input also. Expects length of prompt to be passed to it. Return Value: No value is returned. See Also: ck_get_cmdline, ck_get_nextpar, ck_get_cmdline, ck_input Example: This example reads keyboard from local/remote console into array cmdline[], (filename), then displays file. #include "ckit.h" char prompt1 = "Enter filename to display: "; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); ck_s_puts(prompt1); ck_get_cmdline_raw(strlen(prompt1)); ck_newline(); ck_display_file(cmdline); ck_close_door(); }; }; Functions ck_get_nextpar high level ------------------------------------------------------------------- Summary: #include "ckit.h" char ck_get_nextpar(void); Description: Scans next stacked command from cmdline[] array into "par[]". par defined in CKIT.H Return Value: Returns 0 if none available, non-zero if cmd available See Also: input, get_cmdline, cmdline and par in GLOBAL section. Example: This example reads keyboard from local/remote console into array get_cmdline[], then calls get_nextpar to scan for cmds entered. #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); do { ck_get_cmdline(); /* read input into 'cmdline' */ } while( (ck_DUMP_USER != TRUE) && ( strlen(cmdline) == 0 )); if (ck_get_nextpar()) { /* scan next parameter from cmdline into par */ /* process commands */ switch ( ck_par[0] ) { case 'A': ansi_demo(); break; default: break; }; }; }; ck_close_door(); }; Functions ck_nomore high level ------------------------------------------------------------------- Summary: #include "ckit.h" short ck_nomore(void); Description: Displays prompt: "More: (Enter) or (Y)es, (N)o, (NS)nonstop? ". Returns 0 = Non_stop 1 = Yes 2 = No Also checks for CTRL K. The "More:" prompt will be yellow, the rest will be green. Return Value: short value, meaning described above/ See Also: ck_get_def, ck_get_defyn, ck_get_defen Example: This example loops 3 times to show what each keypress (N,Y or NS) returns. #include "ckit.h" short result, i; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); for(i=0; i <= 2; i++) { ck_s_puts("\r\nReady to test NOMORE 3 times"); ck_newline(); while(!(ck_wait_keypress())) { }; result = ck_nomore(); printf("Nomore() returned %d", result); ck_newline(); }; ck_close_door(); }; Functions ck_get_defyn high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_get_defyn(char *, short) Description: Displays prompt string and either "Enter=yes " or "Enter=no" based on short value. 1st prompt will be yellow, default will be green. If short is Non_zero it will display "Enter=Yes". If short is Zero (NULL) it will display "Enter=No". Calls get_cmdline for user input. Return Value: None See Also: ck_cmd_line, ck_get_def, ck_get_defyn, ck_get_defen Example: This example loops 2 times to show what each value or i displays. #include "ckit.h" short i; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); for(i=0; i <= 1; i++) { ck_s_puts("\r\nReady to test get_defyn()"); ck_newline(); ck_get_defyn("Continue? ", i); ck_s_putv("You entered ", cmdline, NULL); ck_newline(); }; ck_close_door(); }; Functions ck_get_defen high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_get_defen(char *) Description: Same as get_defyn except the default string "(Enter=none?) " will be appended. 1st prompt will be yellow, default will be green. Calls get_cmdline for user input. Return Value: None See Also: ck_cmd_line, ck_get_def, ck_get_defyn, ck_get_defen Example: #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); ck_s_puts("\r\nReady to test get_defne()"); ck_newline(); ck_get_defne("Enter filename? "); ck_s_putv("You entered ", cmdline, NULL); ck_newline(); ck_close_door(); }; Functions ck_getdef high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_get_def(char *, char *) Description: Same as get_defen except both colored prompts are user defineable. The 1st prompt will be yellow, the 2nd one green. Calls get_cmdline for user input. Return Value: None See Also: ck_cmd_line, ck_get_def, ck_get_defyn, ck_get_defen Example: Print 2 prompts, and print user input. static char prompt1 = "Enter filename? " static char prompt2 = "(Enter = quit)"; #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); ck_s_puts("\r\nReady to test get_def()"); ck_newline(); ck_get_def(prompt1, prompt2); ck_s_putv("You entered ", cmdline, NULL); ck_newline(); ck_close_door(); }; Functions ck_prompt_def high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_prompt_def(char *, char *) Description: Same as get_def except it does not call get_cmdline. 1st prompt will be yellow, 2nd prompt green. Return Value: None See Also: ck_cmd_line, ck_get_def, ck_get_defyn, ck_get_defen Example: Print 2 prompts. static char prompt1 = "Enter filename? " static char prompt2 = "(Enter = quit)"; #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); ck_s_puts("\r\nReady to test prompt_def()"); ck_newline(); ck_prompt_def(prompt1, prompt2); ck_get_cmdline(); ck_newline(); ck_close_door(); }; Functions ck_getdefn high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_get_defn(char *, char *) Description: Same as get_def except appends "Enter=none" to end. Calls get_cmdline for user input. Return Value: None See Also: ck_cmd_line, ck_get_def, ck_get_defyn, ck_get_defen Functions ck_dos_shell high level ------------------------------------------------------------------- Summary: #include "ckit.h" short ck_dos_shell(char *, char *); Description: Will execute program pointed arg1, arg2 is passed as command line arguments to the program. arg2 must be < 128 chars. (DOS limit). This function uses spawnlp() to execute the program. If you plan on doing any shells, you need to use this function since it will disable the keyboard timer while the shell is taking place and perform some other clean up's upon re-entry. This call uses C's spawnlp() function, as P_WAIT. Return Value: -1 = error (check 'C's GLOBAL _errno), NULL = NO error See also: F5 local shell to DOS, and CKITDEMO.C Example: Download a file using Zmodem taken from CKITDEMO.C #include "ckit.h" char zmodem_cmds[128]; /* Buffer to build Zmodem command */ main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . color(green); s_printf("\nReady to send %s. Press <ENTER> to begin.",doc_filename); while(DUMP_USER != TRUE) { if( check_CR() ) { break; } } sprintf(zmodem_cmds, "portx %X,%X pB4096 pa3000 handshake cts sz %s", \ uart_base, irq, doc_filename); if(dos_shell("dsz", zmodem_cmds)) { s_puts("\n\aTransfer aborted"); } else { s_puts("\nTransfer complete"); } . . . ck_close_door(); }; }; Functions ck_display_file high level ------------------------------------------------------------------- Summary: #include "ckit.h" short ck_display_file(char *); Description: Displays file to local/remote consoles. Automatic use of page_length, control K checks, MORE? prompting, closes file when done. Expects a pointer to name/path of file to display. If page_length is 0, the MORE? prompting will be disabled. You can use this to your advantage for files that you do not want MORE? prompting by setting ck_userpage_length to 0 before calling display_file(). Just make sure you save the original value of ck_userpage_length if you need it later on. This function will not automatically attempt to display a graphic file if the user is in graphics. For display non-interruptable menus, set page_length to NULL before calling this function. It is up to the door author to decide how he wants to handle it. see below. This call is done to the Borland _open() or MSC _dos_open() libraries as _open(filename, O_RDONLY | O_DENYNONE); (share compatible mode) Return Value: Returns non-zero if error. If desired, you can then check the C global _errno for the cause of the problem. See Also: NONE Example: This example displays the file ckit.m, then forces user to press enter when done. #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . strcpy(filename, "ckit.m") if(!ck_graphics) { (ck_display_file(filename); } else { strcat(filename,"g"); (ck_display_file(filename); } ck_force_enter(); . . . }; ck_close_door(); }; Functions ck_debug_on high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_debug_on(void); alias ck_carrier_on(); Description: A call to this function while debugging your door will disable the keyboard timer among other things while you are trying to debug your door. Make sure you remove this call before releasing your door or the keyboard timeout will not function! It should only be called after open_door();. This can also be used if needed to use transmit_modem() while the door is opened. This will disable ck_DUMP_USER from going true. Make sure you turn debug back on! using debug_off(); Return Value: NONE Example: #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_debug_on(); ck_lower_dtr(); /* Drop user off */ ck_raise_dtr(); ck_wait(1); /* wait for modem to reset */ ck_flush_RQUEUE(); /* Flush receive queue */ ck_transmit_modem("ATDT6159826537"); ck_debug_off(); while(ck_tqueue_len()); /* wait on modem */ ck_newline(); delay(1); while(ck_DUMP_USER != TRUE) { /* wait for modem */ ck_get_cmdline(); ck_newline(); ck_s_putv("Modem returned -> ",cmdline, NULL); break; }; . . . }; ck_close_door(); }; Functions ck_debug_off high level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_debug_on(void); alias ck_carrier_off(); Description: After a call to debug_on(), this will re-enable keyboard timer, etc. It should only be called after open_door(); Return Value: NONE Example: #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); ck_debug_on(); /* while debugging door */ . . . }; ck_debug_off(); ck_close_door(); }; Functions ck_input intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_input(BYTE *, short); Description: Read a line of input with specified length. Echo to screen, leave cursor after the last key typed before C/R. Automatically checks for time_left, carrier. Expects a char array pointer to store input and max. length of input to read. NOTE: Each call to input() will purge the buffer in use to NULLS. MAX length must not exceed the size of your array and it must not include the NULL char. (sizeof(array) - 1). It will also set key_source = 1 or 2. Setting ck_DOTS = char will cause char to be echoed to the local/remote consoles. Return Value: No value is returned. See Also: ck_get_cmdline(), ck_inkey(), ck_getkey(), ck_key_source ck_wait_keypress(), ck_check_CTRL_K Example: This example reads keyboard input from local/remote console into array usr_input[] with max. bytes to read equal to 100 bytes. Will set key_source equal to source of input. NOTE: This a "intermediate" level function. You would not normally need to use this function. get_cmdline(); would normally be used and will handle all input for you. #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_input(&usr_input[0], sizeof(usr_input) - 1); . . . ck_close_door(); }; }; Functions ck_check_time_left intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_check_time_left(void); Description: Checks time left on system, automatically sets ck_DUMP_USER if time expired. Should be included in all major program loops if you are going to use it. Return Value: NONE See Also: display_time, ck_get_cmdline Example: This function is normally handled by get_cmdline() and input(). You do not normally need to use it. #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_check_time_left(); if(ck_DUMP_USER == TRUE) { ck_close_door(); }; . . . ck_close_door(); }; }; ck_mins_left_system intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" short ck_mins_left_system(void); Description: Returns the time left in the door, not including any time_credit given. Does not set ck_DUMP_USER. If expired, the time returned will be 0 or negative minutes. Does not include any time credit given in door. Return Value: short value - minutes remaining in door See Also: display_time, ck_get_cmdline, time_credit Example: #include "ckit.h" minutes_left; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . color(yellow); s_puts("("); color(green); s_printf("%d used, ", system_time_used()+prev_used); color(red); s_printf("%d left", mins_left_system()+time_credit); color(yellow); s_puts(") "); . . . ck_close_door(); }; }; ck_system_time_used intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" short ck_system_time_used(void); Description: Returns the time used in minutes since the door was opened. Does not set ck_DUMP_USER. Does not include time prev used in door. Return Value: short value - minutes used since door opened. See Also: display_time, prev_used Example: #include "ckit.h" minutes_left; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . color(yellow); s_puts("("); color(green); s_printf("%d used, ", system_time_used()+prev_used); color(red); s_printf("%d left", mins_left_system()+time_credit); color(yellow); s_puts(") "); . . . ck_close_door(); }; }; Functions ck_adjust_time_allowed intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_adjust_time_allowed(short); Description: Adjust user time left on system. Automatically updates PCBoard.sys to reflect change. This function will only be effective on systems using pcboard.sys. Return Value: NONE See Also: Example: For complete example see CKITDEMO.C included if (ck_get_nextpar()) { /* scan next parameter from cmdline into par */ if (!strcmpi(thinking_of, par)) { ck_color(green); ck_s_puts("That's right! You get a 10 minute bonus!"); ck_adjust_time_allowed(10); } else { ck_color(blue); ck_s_putv("Wrong! You lose 2 minutes! \ I was thinking of ", thinking_of,".",NULL); adjust_time_allowed(-2); } } Functions ck_check_event intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" short ck_check_event(void); Description: Checks if time left will conflict with event. Return Value: 0 if no conflict, otherwise it will return the minutes left before event. See Also: ck_event_minutes, ck_mins_before_event. EXAMPLE: C-KIT will automatically check for event conflicts. This function would normally not be used. Functions ck_event_minutes intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" short ck_event_minutes(void); Description: Checks minutes past midnight event is scheduled. This function is normally handled by C-KIT. This function would normally not be used. Return Value: Number of minutes past midnight event is scheduled to run. See Also: ck_check_event, ck_mins_before_event. #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_short event_mins; ck_event_mins = event_minutes(); . . . ck_close_door(); }; }; Functions ck_mins_before_event intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" short ck_mins_before_event(void); Description: Check minutes left before event from current time. Return Value: Minutes before event from current time. See Also: ck_check_event, ck_event_minutes. Example: #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . short mins_before_event; mins_before_event = ck_mins_before_event(); . . . ck_close_door(); }; }; Functions ck_delay intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_delay(short); Description: General purpose delay in milliseconds Minumum of 55 ms. (short must be >= 1) This function is good only on the MSC librarys. The TURBO librarys use Borland's DELAY() function. See also: ck_wait Return Value: NONE Functions ck_wait intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_wait(short); Description: General purpose delay in seconds Minumum of 1 sec. for now (short must be >= 1) less than one will result in 1/2 second delay. Use ck_delay above Return Value: NONE See also: ck_delay Functions ck_purge_buffer intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_purge_buffer(BYTE *, short); Description: purge_buffer will purge any buffer to NULLS by passing a pointer to the buffer and the size of the buffer. i.e purge_buffer(buffer, 0x80). This may or may not be useful but is available. NOTE: There is a seperate purge function for the serial port input buffer if you wish to purge it before calling input. See flush_RQUEUE. Return Value: NONE See also: flush_RQUEUE Example: #include "ckit.h" static BYTE buff[256] = "This is purge buffer test"; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_purge_buffer(buff, 255); . . . ck_close_door(); }; }; Functions ck_check_CR intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void short ck_check_CR(void); Description: Check for a carriage return, does not wait, does not display any prompts. Returns TRUE or FALSE Return Value: TRUE, FALSE See also: ck_force_enter(), ck_get_cmdline(), ck_check_keypress() Functions ck_check_CTRL_K intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" short ck_check_CTRL_K(void); Description: Check if a CONTROL K (ASCII 11) has been entered. Returns TRUE or FALSE Return Value: TRUE, FALSE See also: ck_CtrlK_OFF, ck_CtrlK_ON Functions ck_CtrlK_ON intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void CtrlK_ON(void); Description: Enables CONTROL K (ASCII 11) checking. This is normally off since most menu types are non_interruptable. If turned on, CTRL K will be recognized. Once on, you must call CtrlK_OFF() (see below) to disable it. CTRL K's are also NOT put into the input buffer. You have to use the check_CTRL_K() function (see above) to determine if a CTRL K has been pressed. See also: ck_CtrlK_OFF, ck_check_CTRL_K() Functions ck_CtrlK_OFF intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_CtrlK_OFF(void); Description: Disables CONTROL K (ASCII 11) checking. See also: ck_CtrlK_ON, ck_check_CTRL_K() ck_set_kybd_time intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_set_kybd_time(BYTE, BYTE); Description: Sets keyboard timer to desired values. Default is 2 minutes beep and 5 minute timeout. This allows the door author to set the keyboard timer. The time has a resolution in minutes, with a minimum of 1 minute and a maximum of 255. The routine expects two numbers. The first number is the BEEP time. This sets how many minutes should pass before the keyboard timer gives a warning beep. It will continue to beep afterwards at one minute intervals. The second number is the actual keyboard timeout value. It should normally be set to some number higher than the BEEP time. NOTE: Each call to ck_set_kybd_time() will reset the current keyboard timer to zero. Example: Set the BEEP time to 2 minutes and timeout to 6 minutes. #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_set_kybd_time(2, 6); . . . ck_close_door(); }; }; Functions NOTE: ALL the low level functions below are not normally needed and are handled automatically by C-KIT in a higher level function. Most of these functions do NO carrier detects, etc. They are only provided in special cases that may need them. Use with caution. ck_inkey low level ------------------------------------------------------------------- Summary: #include "ckit.h" BYTE ck_inkey(void); Description: Read character (if available) from local/remote console. Does not wait for input. Also sets key_source equal to SYSOP or USER_KEY. Inkey will also keep track of time left and set ck_DUMP_USER if time expires. Return Value: Returns 0 if none available, otherwise returns key pressed See Also: input, sio_getbyte, key_source above in globals, check_CTRL_K Example: This example checks for A at the keyboard, from local/remote console, returns TRUE or FALSE #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . if ( ck_inkey() != 'A') { return(FALSE); } else { return(TRUE); } . . . ck_close_door(); }; }; Functions ck_keystat low level ------------------------------------------------------------------- Summary: #include "ckit.h" short ck_keystat(void); Description: Check if character is available from local console. Does not wait for input. Return Value: Returns 0 if none available. None-zero is available. See Also: ck_input, ck_r_count, ck_key_source. Example: This example checks for keypress at the keyboard local console, returns TRUE or FALSE #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . if ( ck_keystat() ) { return(FALSE); } else { return(TRUE); } . . . ck_close_door(); }; }; Functions ck_r_count low level ------------------------------------------------------------------- Summary: #include "ckit.h" short ck_r_count(void); Description: Check if character is available from remote console. Does not wait for input. Return Value: Returns NULL if none available else returns number of characters in the recieve queue. See Also: ck_input, ck_r_count, ck_keystat. Example: See ck_flush_rqueue below Functions ck_getkey low level ------------------------------------------------------------------- Summary: #include "ckit.h" size_t ck_getkey(void); Description: Read character (if available) from local console. Does not wait for input. Return Value: Returns FALSE if none available. Zero if true. See Also: ck_input, ck_getkey, ck_keystat, ck_check_CTRL_K Example: This example read key from local console buffer and print to screen. #include "ckit.h" size_t ch; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ch = getkey(); ck_s_putc(ch); . . . ck_close_door(); }; }; Functions ck_sio_getbyte low level ------------------------------------------------------------------- Summary: #include "ckit.h" BYTE ck_sio_getbyte(void); Description: Read character (if available) from remote console. Does not wait for input. Return Value: Returns NULL if none available else returns character read. See Also: ck_input, ck_sio_getbyte, ck_keystat, ck_check_CTRL_K Example: This example reads byte from remote console buffer and displays it, if one was available. #include "ckit.h" BYTE ch; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ch = ck_sio_getbyte(); if(ch) { ck_s_putc(ch); }; . . . ck_close_door(); }; }; ck_lower_dtr low level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_lower_dtr(void); Description: Drops DTR on com port, causing modem to hang up. Return Value: NONE See Also: ck_raise_dtr, ck_transmit_modem, ck_transmit_data Example: see ck_transmit_modem below Functions ck_raise_dtr low level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_raise_dtr(void); Description: Raises DTR on com port, causing modem to hang up. Return Value: NONE See Also: ck_lower_dtr, ck_transmit_modem, ck_transmit_data Example: see ck_transmit_modem below Functions ck_force_offhook low level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_force_offhook(void); Description: Drops DTR on com port, causing modem to hang up, tells modem to go back offhook. This function will wait 1 second after dropping dtr and 2 seconds after raising DTR before telling modem to go offhook. This is normally handled automatically by C-KIT depeding on the ck_FORCEOFFHOOK setting. Return Value: NONE See Also: ck_FORCEOFFHOOK above. Example: Send a string to reset the modem if carrier is lost. #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_force_offhook(); /* Dump user offline */ . . . }; ck_close_door(); }; Functions ck_transmit_data low level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_transmit_data(BYTE *); Description: Send C string to remote console. No echo to local console. Expects a pointer to either a NULL terminate C string of type BYTE or char. Check for carrier included. To send a single byte use the sample code below. Return Value: NONE See Also: ck_transmit_modem Example: #include "ckit.h" #define BEEP 0x07 static char remote_msg[] = "HELLO"; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_transmit_data(remote_msg); send_byte(BELL); . . . }; ck_close_door(); }; /* To send a single byte to the remote only use this code: */ void send_byte(BYTE data) { BYTE byte_out[2]; *byte_out = data; *(byte_out+1) = 0x00; /* Make a 'C' string */ transmit_data(byte_out); } ck_transmit_modem low level ------------------------------------------------------------------- Summary: #include "ckit.h" short ck_transmit_modem(BYTE *); Description: Send C string to modem/remote. No echo to local console. Expects a pointer to either a NULL terminate C string of type BYTE or char. NO carrier checking is included. If it returns Non-Zero if error occured, otherwise it returns NULL. Return Value: NONE See Also: ck_transmit_data Example: #include "ckit.h" static char dialnumber[] = "ATDT6159707418"; #include "ckit.h" main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_debug_on(); ck_lower_dtr(); /* Drop user off */ ck_raise_dtr(); ck_wait(1); /* wait for modem to reset */ ck_flush_RQUEUE(); /* Flush receive queue */ ck_transmit_modem(dialnumber); ck_debug_off(); while(ck_tqueue_len()); /* wait on modem */ ck_get_cmdline(); strcmp(ck_cmdline, "CARRIER"); . . . }; ck_close_door(); }; Functions ck_tqueue_len low level ------------------------------------------------------------------- Summary: #include "ckit.h" short ck_tqueue_len(void); Description: Check number of bytes left in Transmit RQUEUE. Normally this routine is not needed but is available if needed. Return Value: Bytes left in XMIT QUEUE See Also: Example: #include "ckit.h" static char modem_msg[] = "ATX4"; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_debug_on(); ck_transmit_modem(message); while(ck_tqueue_len()); ck_debug_off(); . . . }; ck_close_door(); }; Functions ck_flush_RQUEUE low level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_flush_RQUEUE(void); Description: Flush bytes from Receive QUEUE buffer. Return Value: NONE See Also: r_count, tqueue_len Example: #include "ckit.h" static char message[] = "ATH1"; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_flush_RQUEUE(); /* flush buffer */ ck_transmit_modem(message); while (ck_r_count()); /* wait for response back */ . . . }; ck_close_door(); }; Functions ck_flush_TQUEUE low level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_flush_TQUEUE(void); Description: Flush bytes from Transmit QUEUE buffer. Return Value: NONE See Also: tqueue_len Example: #include "ckit.h" static char message[] = "ATH1"; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . ck_flush_RQUEUE(); /* flush buffer */ ck_transmit_modem(message); while (ck_r_count()); /* wait for response back */ . . ck_flush_TQUEUE(); /* flush buffer */ . }; ck_close_door(); }; Functions ck_check_cd low level ------------------------------------------------------------------- Summary: #include "ckit.h" BYTE ck_check_cd(void); Description: Checks if carrier present. If present, returns NON-zero. Zero (NULL) means no carrier present. Return Value: BYTE indicator of carrier present. See Also: ck_DUMP_USER, ck_transmit_data, ck_transmit_modem Functions ck_check_keypress low level ------------------------------------------------------------------- Summary: #include "ckit.h" short ck_check_keypress(BYTE); Description: Check for any specific ASCII character entered. Does not wait for a character. This function may or may not be useful but is available if needed for a "hot_key" function in a door. Does no carrier checking! Return Value: TRUE, FALSE See also: ck_check_CR, ck_input(), ck_getkey() ck_wait_keypress, ck_check_CTRL_K Example: #include "ckit.h" BYTE result; main(int argc, char **argv) { if (argc > 1) { ck_open_door(argv[1]); . . . while { !(result = ck_check_keypress(0x41)); }; printf("Keypress returned %d", result); . . . }; ck_close_door(); }; C-KIT based DOOR programs have many of the feature available for the door author, and for the sysop using standard function keys such as: Function key ------------ F5 Shell to DOS F8 Return user to system F9 Toggle display on/off F10 Chat mode (use the ESCAPE key to exit) * F3 Toggle printer on/off * F4 Toggle pagebell on/off * F7 Toggle caller alarm on/off Alternate key ------------- ALT-H Toggle between different status lines * ALT-N Toggle sysop on next * ALT-X Toggle exit to dos after call and help lines Alternately pressing the ALT-H key will bring up the next status line screen. The 1st screen is a help screen, the second second screen shows your COM port status. * The function keys marked with an "*" will only be of use to systems using pcboard.sys. The rest are functional with any system. Command stacking is also available and can be easily disabled if desired. See the CKITDEMO.C for example of disabling command stacking. Files ------- C-KIT.DOC - This file. CKITDEMO.EXE - This is a very short program written to test C-KIT libraries and for a short demo. CKITDEMO.EXE is a compiled program using the C-KIT library. CKIT.H - This is a standard C header file, to be included with your door program. This file contains all the function prototypes, and variable names and types available from C-KIT. CKIT_MS.LIB - This file is the C-KIT library file to access all of the C-KIT CKIT_MM.LIB files that are linked into your door program for MSC. CKIT_TS.LIB - This file is the C-KIT library file to access all of the C-KIT CKIT_TM.LIB files that are linked into your door program for TURBO C. CKITDEMO.C - The source code for CKITDEMO demostrating a door written using C-KIT functions. DEMO.BAT - Sample .bat file to compile and link using the C-KIT.LIB Provided as an example. CKIT_TC.ZIP - Contains TURBO C files TCREAD.ME - Information for TURBO C users CKITDEMO.MAK - TURBO C Make file for CKITDEMO door (for use as example)* CKITS.PRJ - TURBO C Project file for CKITDEMO door (use as example)* TCPPCKIT.PRJ - TURBO C++ Project file for CKITDEMO door (use as example)* * For small models ATTENTION TURBO C USERS: In versions 2.01 and below you should use WORD alignment, in C-kit 2.08 and above you should use BYTE alignment. This applies if you are planning to use the ck_users structure AND/OR the ck_update_user() function. The default on BORLAND is BYTE alignment. This will not work correctly for these two items. If you are not using either the ck_users file structure or ck_update_user(); function, then you don't have to use WORD alignment, BYTE alignment will work OK. See the file TCREAD.ME in the CKIT_TC.ZIP file. In addition, TURBO C++/BC++ users should also select standard stack frame alignment. Make a dir to work from. Copy the CKITDEMO.C, CKITDEMO.H, CKIT.H, the CKIT_T?.LIB's, and the TCPPCKIT.PRJ or CKITS.PRJ into the same dir. Bring up the TURBO C IDE and select the proper project file and you can test the CKITDEMO.C. Have it create an .exe file. This should get you started. You can take it from here... This package can be freely distributed so long as it is not modified or sold for profit. If you find that this program is valuable, you can send me a donation for what you think it is worth. I suggest at least $25.00 (USA exchange). You will receive a program CKITREG.EXE. This will register all future copies of C-KIT with your registration number. This means you would only have to download the new versions from your favorite board, saving you long distance charges! For registration over $25.00, full access to all Nodes on Data-Comp will be made available. Source code modules are available to registered users for reading other system files that you may want to include in your door program. (as they become available). There is now a complete set of PCBoard source code modules. (users.sys, pcboard.dat etc) Send your contributions to: Rickie W. Belitz P.O. Box 5895 Maryville, TN 37802-5895 SUPPORT ----------- If you have any questions, suggestions, or bug reports, contact me at: Data-Comp BBS (615) 982-8723 (Hayes Ultra V.32) (public line) (615) 982-6537 (Hayes Ultra V.32) (private line) (615) 982-6512 (USR HST Dual Standard V.32), (private line) (615) 970-7418 (USR HST Dual Standard V.32), (private line) NOTE: The board has automatic rollover on the phone lines. There is chance you could end up on one of the private lines with limited time. I can also be reached via mail networks thru INTELEC's BBS_DOORS conference and RIME's (Relaynet) DOORS conference. ACKNOWLEDGEMENTS -------------------- I would like to give special thanks to my Co-sysop, Dean McGuire, who has patiently tested the door routines and for help preparing the documentation. GENERIC.SYS -------------------------- For maximum compatibility, C-KIT will also read a file called GENERIC.SYS. This file can be created by the sysop desiring to run the door and allow C-KIT to operate. This would allow your door to operate on ANY BBS system. (see compatibilty issues below). The GENERIC.SYS file is a standard ASCII file and contains 3 lines, each followed by a carriage return, line feed. The format is: line 1 - The BBS operator's name. line 2 - The COM port in use. line 3 - Time allowed in door. When C-KIT finds a GENERIC.SYS, it will ask the user for his/her first and last names before opening the door. After the user inputs their name, the door will continue to load and run. Below is an example GENERIC.SYS file with a sysop name of Rickie, using Com port 1, and allowing 50 minutes in the door. Rickie COM1: 50 Each line is followed by a C/R, L/F and the com port follows the same format as the standard door.sys. COM0: = Local Mode (same as door.sys) See the compatibilty issues below for more information. NOTE: You should include this information in your door documentation also. COMPATIBILITY ISSUES -------------------------- Although C-KIT makes a lot information available to the user, the author has to decide on what particular information his or her door will require. Here are some general guidelines that may help. Decide on exactly what information your door will need to operate. Keeping this to a minimum increases your chances of maintaining compatibility thruout the different BBS's systems and versions thereof which C-KIT supports. For example, let's assume you are designing a standard BBS game. C-KIT handles all the detailed information such as time left, carrier detect etc. All you would really need is some basic information. Perhaps just the user's name and sysop name. By keeping this type of information to the minimum, your door would work regardless of whether the sysop running your door used pcboard.sys, door.sys, callinfo.bbs or GENERIC.SYS on the command line..i.e, game.exe c:\pcb\pcboard.sys OR game.exe c:\pcb\door.sys OR game.exe c:\wc\callinfo.bbs, OR game.exe c:\GENERIC.SYS OR game.exe c:\rbbs\DORINFOx.DEF;, ANY of these would work. (If the sysop was running PCBoard 12.0, he would only be able to use pcboard.sys. In this case, C-KIT would not only take care of deciding if it was a pcboard.sys file, door.sys file, WILDCAT! callinfo.bbs or DORINFOx.DEF, but also if it *is* a pcboard.sys file, whether it is a PCBoard 12.0 sys file or later, and then would read it properly!). This would make your door compatible with the full spectrum of PCBoard 12.0-14.5, WILDCAT!, GAP, SPITFIRE 3.0, other systems using the standard door.sys file, RBBS and others using DORINFO1.DEF and ANY BBS using GENERIC.SYS with minimum effort on the part of the sysop running your door. Once you've written this fantastic new door, if it's a snap for a Sysop to install it, this might make him a bit more inclined to register it, right? Another senario would be if your door needs somewhat more than the basic information. I would recommend using the variables available in door.sys and WILDCAT! info file in this case. This would give you the broadest coverage for your door. If you will notice in the variables descriptions in this manual, there is a compatibility list to the right of each variable. This tells you which and what type of information is available to you depending on whether your door found a door.sys, pcboard.sys (and which version of PCBoard), WILDCAT! info file and DORINFOx.DEF file. Below is a summary and quick guide to each pcboard.sys version, door.sys, WILDCAT!, DORINFOx.DEF info file and which information variables are available with each. If you need EVEN more information, then you can tell C-KIT to open the users file and read information. Doing so will limit your door to PCBoard systems only. C-KIT will NOT record any information to the user's file unless a call to update_user has been made. It will also not record anything to sysop record. Compatible with... ---------------------------------------------------------- "ck_" PCBoard.sys Variables 12.0 14.0-14.5 DOOR.SYS WILDCAT! DORINFOx.DEF GENERIC.SYS -------------- ---- -------- -------- ------- ----------- ----------- *conferences X X aport X X X X X X ansi_ng X BBSname X bps_open X X X baud_rate X X X X X callalarm X X X current_conf X X X caller_bday X X display X X X X X default_color X daily_bytes X X daily_files X X download_Kbytes X X door_opened X DOTS X X X X X X dload_total X X X error_connection X X X X expert X X X X event_active X event_slide X event_time X X X firstname X X X X X X fullname X X X X X X graphics X X X X X gen_dir X high_msg X key_source X X X X X local X X X X X logoff_color X X X X exit_msg X X X X X language X X last_file_scan X X X X min_left X X X X X X main_dir X max_files X max_sec X monitor_type X msgs_left X name_in_use X netchat X X node X X X X NO_FKEYS X X X X X X NOSYSTEM X X X X X X printer X X X protocol X X X X pagebell X X X password X X X X page_length X X X X X PCB X X X X X PCB12 X X X X X prev_used X port X X X X X parity X X RBBS X X X X X X record_lock X scan_code X X X X X security_level X X X silent X X X X X X sysop_next X X sysop_name X X X sysop_alias X time_logged X X X X X time_on X X time_limit X X time_added X X total_doors X user_record X X X X upload_Kbytes X upload_total X X X ck_usercomment1 X WILDCAT X X X X X One last note - There are four variables PCB12, PCB, WILDCAT and GAP. When C-KIT reads a pcboard.sys file, it will set the PCB variable TRUE. If the pcboard.sys file it read was a 12.0 file, it will set the PCB12 variable true. If C-KIT finds a WILDCAT system, it will set the variable WILDCAT true. This may be useful in making adjustments to your program depending on which system file was read (PCB, DOOR.SYS, PCB12, WILDCAT) and/or if a sysop was running PCBoard 12.0 and you normally expected door.sys or wildcat info file. If C-KIT finds a door.sys file, GAP will be set true. Also, see the users file information earlier in the doc file. Some of the users structure information is available even if you are just using door.sys. If you do tell C-KIT to open the users file, all the users file information above will be available, if C-KIT finds a version 14.x pcboard.sys. If it finds a PCBoard 12.0 pcboard.sys file, some, but not all, of the users structure information will be available. Each member of the users structure is marked to indicate what is available and what is not depending on the things just mentioned. Warranty Warranty ------------ I make no warranty of any kind, express or implied, including without limitation, any warranties of merchantability and/or fitness for a particular purpose. I shall not be held liable for any damages, whether direct, indirect, special or consequential arising from a failure of this program to operate in the manner desired by the user. I shall not be held liable for any damage to data or property which may be caused directly or indirectly by the use of this program. In no event will I be held liable for any damages, including (but not limited to) any lost profits, lost savings or other incidental or consequential damages arising out of the use or inability to use this program, or for any claim by any other party. This warranty is governed by the laws of the State of Tennessee. ORDER.FRM v2.1 ------------- Return to: Rickie Belitz P.O. Box 5895 Maryville, TN 37802-5895 Name ______________________________________________________________ Company ___________________________________________________________ Address ___________________________________________________________ ___________________________________________________________ Phone _____________________________________________________________ Register C-KIT to: Name____________________________________________ Diskette size: ____ 5.25" acceptable ____ 3.5" required* Orders outside the USA add $4.00 _________ *Add $4.00 for 3.5" diskettes 720K ___ 1.44 ___ _________ Please find enclosed a check or money order for USA $_________ ($25.00 suggested) payable to Rickie Belitz. This shows my support of Shareware products and the Shareware concept. It also shows my encouragement to help further development of C-KIT. I understand that C-KIT is provided as-is and no warranties of any kind, expressed or otherwise, are included and that I am using it at my own risk. Signed: _________________________________________ Date: _________ RELEASE HISTORY ------------------- see history file SOME COMMON PROBLEMS/QUESTIONS ------------------------------ Q. How can a test my door in "local" mode? A. There is a door.sys file included with the C-KIT libraries. The first line in the door.sys file is COM0:. With accordance to doorsys specs., this specifies "local" mode. Use this file for testing your doors. You can modify the door.sys file to also use a com port for online testing. See the doorsys.txt for more information. You could also make up a GENERIC.SYS file and use COM0: as the port. See the section on GENERIC.SYS. Q. When linking my code with the library I get a linker error - Unresolved external _progname in CKIT3.ASM. A. C-KIT will look for a C string array called progname[21];. This the name of your door program and will appear at the bottom of the local line. This is not an option. You must declare some kind of name for C-KIT to use even if it just a space char if you don't want your progname at the bottom. See the CKIDEMO.H file for example and the variable progname[] in the doc file. Q. When linking your ckitdemo program, I get an error - Unresolved external _random in ckitdemo.c A. The Ckitdemo.c door was written to be compiled with either Microsoft C or Turbo C. As such, there are compiler directives in the CKITDEMO.C file that will take appropriate action depending on the compiler. Therefore, when compiling the CKITDEMO.C program, you must have the statement -DCOMPILER=MICROSOFT or -DCOMPILER=TURBOC on the command line. This is needed only when compiling the CKITDEMO.C program. It is NOT needed when you are compiling your own door program. Q. Do I have to include the -DCOMPILER-MICROSOFT or -DCOMPILER=TURBOC on the command line every time I compile my door program? A. No, this was only needed for the CKITDEMO.C source code. You can also modify the ckitdemo.c and ckitdemo.h file and take the compiler directives out if you like. Then you would not have to use it when compiling the ckitdemo.c. (Just make sure you take the right ones out for whichever compiler you are using). Matter fact, the way the defaults are defined in CKITDEMO.C, and CKITDEMO.H you don't need to have the -DCOMPILER=TURBOC when using TURBO C to compile the ckitdemo.c file or using Turbo C's IDE. Q. My F4, F3, F7, ALT X, ALT N keys do not do have any effect when returning to the BBS. A. These keys are valid only on doors or sysops using the pcboard.sys file. When the code finds a door.sys or Wildcat! info files, it will make no attempt to update a pcboard.sys file. F5 shell to DOS, F8 return to BBS, F9 screen on/off will work with any system. Try and write your door so that the sysop can use pcboard.sys if he is a PCBoard sysop but will also run on other systems as well. Future updates will take into consideration other systems as permitted. See the compatibility chart above. Q. Why all the formfeeds in the documentation? A. This is so that people with access to a copier can print them out, run the printed sheets thru the copier and duplex (print on both sides) the sheets into a manual. If you do not want the form feeds, just do a global replacement with your favorite editor and get rid of them. Q. I thought C-KIT required that the users file path be listed also? A. NO. This was used for the CKITDEMO file only. C-KIT library does not care one way or another about the users file being open. CKITDEMO is also written to work with ANY system. Ckitdemo is a demostration of how a door can be written to accept any command line given and make adjustments accordingly. Ckitdemo will accept either: ckitdemo.exe c:\pcb\pcboard.sys c:\pcb\main\users ckitdemo.exe c:\pcb\door.sys ckitdemo.exe c:\wc\callinfo.bbs PORT:03e8:5 See the open_door() function for more information. Q. Will C-KIT work with any systems users file? A. NO. If you require information from the user file it must be be PCBoard 14.x or PCBoard 12.0. However, by doing so you will be limiting your door to the number of systems it can be ran on. I would not recommend using user file info unless your door is being written specifically for PCBoard. Other system files (pcboard.dat, msgs and other systems users file) will be included in the form of source code at a later date. This will allow you to link those with the existing C-KIT library functions. Q. What baud rates can C-KIT can handle? A. C-KIT can handle ANY baud rate from 50 baud to 230K baud. (these are the baud rates it has been used with). The highest baud any standard IBM compt. system can produce is 115K baud. The 230K baud was done on a modified IBM AT by changing the UART's xtal and using 16550A UARTs. Q. I'm using MSC 6.0 and when I compile my program I get a message "warning 'NULL' : macro redefinition"? A. This is not a problem. It is actually a carry over from MSC5.1. If you wish, you can remove the line #define NULL = 0 in the CKIT.H header file. MSC 6.0 redefined their NULL assignment in the stdlib.h file which causes this. You will not get the warning with MSC 5.1 or lower and TURBO C. Q. I'm using TURBOC and when I compile the small model demo program it works fine. But when I re-compile using medium model I get stack overflow fixup errors from the linker. A. TurboC does not delete and re-compile the CKITDEMO.C module. So when it attempts to link the older small model .obj file you created earlier with the medium library, you will get this error. When you switch memory models, you must delete the previous .obj file created using the small memory model. If this happened to be CKITDEMO.C, you would need to delete CKITDEMO.OBJ before changing memory models. Q. Some function keys are not trapped locally. A. Some keys are reserved on the local keyboard for sysop functions. Try to design your door without using the F3, F4, F5, F7, F8, F9 ALT-H, ALT-N, ALT-X. If you have to use these keys, they can be used by the remote keyboard but just be aware, you would not be able to use them on your local keyboard. Q. When linking my program, I get an error - Unresolved external _wait. A. This function was renamed to ck_wait in v1.7. You need to be using the CKIT.h header file. There was a conflict with one of Borland's library names. Q. Why does the user security level somtimes show on the status line and sometimes it doesn't? A. PCBoard.sys file does not provide that information. The security level will only show if you are using door.sys, callinfo.bbs (WILDCAT!) or you are using pcboard.sys and open the users file. The status line indicators for pagebell, printer and caller alarm will also not show up if you are using door.sys or callinfo.bbs but will if you are using any version of pcboard.sys from 12.0 up. Q. Will there be any kind of sign off message from C-KIT after the program is registered? A. After C-KIT is registered, the only message displayed when closing the door will be the one you defined using the *ck_logoff_msgs or the default "Returning to system ...".